Skip to main content

NDK

The comprehensive toolkit for building Nostr applications. Modern, performant, and framework-ready.

Overview​

NDK (Nostr Development Kit) is a monorepo containing everything needed to build modern Nostr clients. From reactive UI bindings to advanced protocols like Web of Trust and Negentropy sync, NDK provides the building blocks for professional Nostr applications.

Key Features​

Modern Architecture​

┌─────────────────────────────────────────────────────┐
│                    Your App                          │
├─────────────────────────────────────────────────────┤
│     Framework Bindings (Svelte/React/React Native)  │
├─────────────────────────────────────────────────────┤
│                    NDK Core                          │
│  ┌─────────┐  ┌──────────┐  ┌────────────────────┐ │
│  │ Events  │  │ Signers  │  │ Wallet Integration │ │
│  └─────────┘  └──────────┘  └────────────────────┘ │
│  ┌─────────┐  ┌──────────┐  ┌────────────────────┐ │
│  │ Relays  │  │ Caching  │  │ Web of Trust       │ │
│  └─────────┘  └──────────┘  └────────────────────┘ │
└─────────────────────────────────────────────────────┘
  • TypeScript — Full type safety
  • Reactive — Built for modern UI frameworks
  • Modular — Use only what you need
  • Well-documented — Comprehensive API docs

Framework Support​

FrameworkPackageStatus
Svelte 5@nostr-dev-kit/ndk-svelteFirst-class
React@nostr-dev-kit/ndk-reactFull support
React Native@nostr-dev-kit/ndk-mobileMobile-ready
Vanilla JS@nostr-dev-kit/ndkCore

Outbox Model​

NDK pioneered outbox model support for intelligent relay management:

import NDK from '@nostr-dev-kit/ndk';

const ndk = new NDK({
  outboxRelayUrls: ['wss://purplepag.es'],
  enableOutboxModel: true,
});

// NDK automatically discovers where users publish
// No manual relay configuration needed

Session Management​

Built-in multi-account sessions with persistence:

// Login with browser extension (NIP-07)
const user = await ndk.signer.user();

// Or with private key
import { NDKPrivateKeySigner } from '@nostr-dev-kit/ndk';
const signer = new NDKPrivateKeySigner(privateKey);
ndk.signer = signer;

// Session persists automatically

Wallet Integration​

Seamless support for Cashu, NWC, and WebLN:

import { NDKCashuWallet, NDKNWCWallet } from '@nostr-dev-kit/ndk';

// Cashu wallet
const cashuWallet = new NDKCashuWallet(ndk);

// NWC wallet
const nwcWallet = new NDKNWCWallet(ndk);
nwcWallet.connectionString = 'nostr+walletconnect://...';

// Reactive balance tracking
wallet.balance.subscribe(bal => console.log(bal));

Caching Adapters​

Multiple storage backends:

AdapterUse Case
DexieBrowser IndexedDB
RedisServer-side
SQLiteMobile/Desktop
In-memoryTesting
Nostr relayDistributed cache
import NDKCacheAdapterDexie from '@nostr-dev-kit/ndk-cache-dexie';

const cacheAdapter = new NDKCacheAdapterDexie({ dbName: 'myapp' });
const ndk = new NDK({ cacheAdapter });

Web of Trust​

Filter content based on social graph:

const wot = await ndk.getWoT(user);
const trustScore = wot.getTrustScore(otherUser);

Installation​

# Core
npm install @nostr-dev-kit/ndk

# With React
npm install @nostr-dev-kit/ndk @nostr-dev-kit/ndk-react

# With Svelte
npm install @nostr-dev-kit/ndk @nostr-dev-kit/ndk-svelte

# With caching
npm install @nostr-dev-kit/ndk @nostr-dev-kit/ndk-cache-dexie

Quick Start​

import NDK, { NDKEvent } from '@nostr-dev-kit/ndk';

// Initialize
const ndk = new NDK({
  explicitRelayUrls: [
    'wss://relay.damus.io',
    'wss://nos.lol',
  ],
});

await ndk.connect();

// Fetch events
const events = await ndk.fetchEvents({
  kinds: [1],
  authors: ['pubkey...'],
  limit: 20,
});

// Publish
const event = new NDKEvent(ndk);
event.kind = 1;
event.content = 'Hello from NDK!';
await event.publish();

React Example​

import { NDKProvider, useNDK, useEvents } from '@nostr-dev-kit/ndk-react';

function App() {
  return (
    <NDKProvider
      relayUrls={['wss://relay.damus.io']}
    >
      <Feed />
    </NDKProvider>
  );
}

function Feed() {
  const { events } = useEvents({
    kinds: [1],
    limit: 50,
  });

  return (
    <div>
      {events.map(event => (
        <Note key={event.id} event={event} />
      ))}
    </div>
  );
}

Svelte Example​

<script>
  import { ndkStore, eventStore } from '@nostr-dev-kit/ndk-svelte';

  const events = eventStore($ndkStore, {
    kinds: [1],
    limit: 50,
  });
</script>

{#each $events as event}
  <Note {event} />
{/each}

Packages​

PackageDescription
@nostr-dev-kit/ndkCore library
@nostr-dev-kit/ndk-svelteSvelte 5 bindings
@nostr-dev-kit/ndk-reactReact hooks
@nostr-dev-kit/ndk-mobileReact Native
@nostr-dev-kit/ndk-cache-dexieIndexedDB cache
@nostr-dev-kit/ndk-cache-redisRedis cache
@nostr-dev-kit/ndk-walletWallet support

Testing​

NDK provides testing utilities:

import { RelayPoolMock, UserGenerator, EventGenerator } from '@nostr-dev-kit/ndk';

const mockPool = new RelayPoolMock();
const testUser = UserGenerator.create();
const testEvent = EventGenerator.create({ kind: 1 });

Philosophy​

Besides improving the developer experience, the core goal of NDK is to improve the decentralization of Nostr via intelligent conventions and data discovery features without depending on any one central point of coordination.

See Also​