NDK

Appearance

Usage ​

Instantiate an NDK instance ​

You can pass an object with several options to a newly created instance of NDK.

  • explicitRelayUrls – an array of relay URLs.
  • signer - an instance of a signer.
  • cacheAdapter - an instance of a Cache Adapter
  • debug - Debug instance to use for logging. Defaults to debug("ndk").
ts
// Import the package
import NDK from "@nostr-dev-kit/ndk";

// Create a new NDK instance with explicit relays
const ndk = new NDK({
    explicitRelayUrls: ["wss://a.relay", "wss://another.relay"],
});

If the signer implements the getRelays() method, NDK will use the relays returned by that method as the explicit relays.

ts
// Import the package
import NDK, { NDKNip07Signer } from "@nostr-dev-kit/ndk";

// Create a new NDK instance with just a signer (provided the signer implements the getRelays() method)
const nip07signer = new NDKNip07Signer();
const ndk = new NDK({ signer: nip07signer });

Note: In normal client use, it's best practice to instantiate NDK as a singleton class. See more below.

Connecting ​

After you've instatiated NDK, you need to tell it to connect before you'll be able to interact with any relays.

ts
// Import the package
import NDK from "@nostr-dev-kit/ndk";

// Create a new NDK instance with explicit relays
const ndk = new NDK({
    explicitRelayUrls: ["wss://a.relay", "wss://another.relay"],
});
// Now connect to specified relays
await ndk.connect();

Architecture decisions & suggestions ​

  • Users of NDK should instantiate a single NDK instance.
  • That instance tracks state with all relays connected, explicit and otherwise.
  • All relays are tracked in a single pool that handles connection errors/reconnection logic.
  • RelaySets are assembled ad-hoc as needed depending on the queries set, although some RelaySets might be long-lasting, like the explicitRelayUrls specified by the user.
  • RelaySets are always a subset of the pool of all available relays.