INDEX.md raw

NDK (Nostr Development Kit) Claude Skill

Comprehensive knowledge base for working with NDK in production applications

This Claude skill provides deep expertise in the Nostr Development Kit based on real-world usage patterns from the Plebeian Market application.

📚 Documentation Structure

.claude/skills/ndk/
├── README.md                    # This file - Overview and getting started
├── ndk-skill.md                 # Complete reference guide (18KB)
├── quick-reference.md           # Fast lookup for common tasks (7KB)
├── troubleshooting.md           # Common problems and solutions
└── examples/                    # Production code examples
    ├── README.md
    ├── 01-initialization.ts     # NDK setup and connection
    ├── 02-authentication.ts     # NIP-07, NIP-46, private keys
    ├── 03-publishing-events.ts  # Creating and publishing events
    ├── 04-querying-subscribing.ts # Fetching and real-time subs
    └── 05-users-profiles.ts     # User and profile management

🚀 Quick Start

For Quick Lookups

Start with `quick-reference.md` for:

For Deep Learning

Read `ndk-skill.md` for:

For Problem Solving

Check `troubleshooting.md` for:

For Code Examples

Browse `examples/` directory for:

📖 Core Topics Covered

1. Initialization & Setup

2. Authentication

3. Event Publishing

4. Querying & Subscriptions

5. User & Profile Management

6. Advanced Patterns

🎯 Use Cases

Building a Nostr Client

// Initialize
const { ndk, isConnected } = await initializeNDK({
  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
  timeoutMs: 10000
})

// Authenticate
const { user } = await loginWithExtension(ndk)

// Publish
await publishBasicNote(ndk, 'Hello Nostr!')

// Subscribe
const sub = subscribeToNotes(ndk, user.pubkey, (event) => {
  console.log('New note:', event.content)
})

Building a Marketplace

// Publish product
await publishProduct(ndk, {
  slug: 'bitcoin-shirt',
  title: 'Bitcoin T-Shirt',
  price: 25,
  currency: 'USD',
  images: ['https://...']
})

// Create order
await createOrder(ndk, {
  orderId: uuidv4(),
  sellerPubkey: merchant.pubkey,
  productRef: '30402:pubkey:bitcoin-shirt',
  quantity: 1,
  totalAmount: '25.00'
})

// Monitor payment
monitorPaymentReceipt(ndk, orderId, invoiceId, (preimage) => {
  console.log('Payment confirmed!')
})

React Integration

function Feed() {
  const ndk = useNDK()
  const { user } = useAuth()
  
  // Query with real-time updates
  const { data: notes } = useNotesWithSubscription(
    ndk,
    user.pubkey
  )
  
  return (
    <div>
      {notes?.map(note => (
        <NoteCard key={note.id} note={note} />
      ))}
    </div>
  )
}

🔍 Common Patterns Quick Reference

Safe NDK Access

const ndk = ndkActions.getNDK()
if (!ndk) throw new Error('NDK not initialized')

Subscription Cleanup

useEffect(() => {
  const sub = ndk.subscribe(filter, { closeOnEose: false })
  sub.on('event', handleEvent)
  return () => sub.stop()  // Critical!
}, [ndk])

Error Handling

try {
  await event.sign()
  await event.publish()
} catch (error) {
  console.error('Publishing failed:', error)
  throw new Error('Failed to publish. Check connection.')
}

Tag Filtering

// ✅ Correct (note the # prefix for tag filters)
{ kinds: [16], '#order': [orderId] }

// ❌ Wrong
{ kinds: [16], 'order': [orderId] }

🛠 Development Tools

VS Code Integration

These skill files work with:

Debugging Tips

// Check connection
console.log('Connected relays:', 
  Array.from(ndk.pool?.relays.values() || [])
    .filter(r => r.status === 1)
    .map(r => r.url)
)

// Verify signer
console.log('Signer:', ndk.signer)
console.log('Active user:', ndk.activeUser)

// Event inspection
console.log('Event:', {
  id: event.id,
  kind: event.kind,
  tags: event.tags,
  sig: event.sig
})

📊 Statistics

🔗 Additional Resources

Official NDK Resources

Nostr Protocol

Related Tools

💡 Tips for Using This Skill

  1. Start Small: Begin with quick-reference.md for syntax
  2. Go Deep: Read ndk-skill.md section by section
  3. Copy Examples: Use examples/ as templates
  4. Debug Issues: Check troubleshooting.md first
  5. Stay Updated: Patterns based on production usage

🤝 Contributing

This skill is maintained based on the Plebeian Market codebase. To improve it:

  1. Document new patterns you discover
  2. Add solutions to common problems
  3. Update examples with better approaches
  4. Keep synchronized with NDK updates

📝 Version Info

Ready to build with NDK? Start with quick-reference.md or dive into examples/01-initialization.ts!