next.orly.dev/.claude/skills/ndk/INDEX.md

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:

• Common code snippets
• Quick syntax reminders
• Frequently used patterns

For Deep Learning

Read ndk-skill.md for:

• Complete API documentation
• Best practices
• Integration patterns
• Performance optimization

For Problem Solving

Check troubleshooting.md for:

• Common error solutions
• Performance tips
• Testing strategies
• Debug techniques

For Code Examples

Browse examples/ directory for:

• Real production code
• Full implementations
• React integration patterns
• Error handling examples

📖 Core Topics Covered

1. Initialization & Setup

• Basic NDK initialization
• Multiple instance patterns (main + zap relays)
• Connection management with timeouts
• Relay pool configuration
• Connection status monitoring

2. Authentication

• NIP-07: Browser extension signers (Alby, nos2x)
• NIP-46: Remote signers (Bunker)
• Private Keys: Direct key management
• Auto-login with localStorage
• Multi-account session management

3. Event Publishing

• Basic text notes
• Parameterized replaceable events (products, profiles)
• Order and payment events
• Batch publishing
• Error handling patterns

4. Querying & Subscriptions

• One-time fetches with fetchEvents()
• Real-time subscriptions
• Tag filtering patterns
• Time-range queries
• Event monitoring
• React Query integration

5. User & Profile Management

• Fetch profiles (npub, hex, NIP-05)
• Update user profiles
• Follow/unfollow operations
• Batch profile loading
• Profile caching strategies

6. Advanced Patterns

• Store-based NDK management
• Query + subscription combination
• Event parsing utilities
• Memory leak prevention
• Performance optimization

🎯 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:

• Cursor AI for code completion
• Claude for code assistance
• GitHub Copilot with context

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

• Total Documentation: ~50KB
• Code Examples: 5 complete modules
• Patterns Documented: 50+
• Common Issues Covered: 15+
• Based On: Real production code

🔗 Additional Resources

Official NDK Resources

• GitHub: https://github.com/nostr-dev-kit/ndk
• Documentation: https://ndk.fyi
• NPM: @nostr-dev-kit/ndk

Nostr Protocol

• NIPs: https://github.com/nostr-protocol/nips
• Nostr: https://nostr.com

Related Tools

• TanStack Query: React state management
• TanStack Router: Type-safe routing
• Radix UI: Accessible components

💡 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

• Skill Version: 1.0.0
• NDK Version: Latest (based on production usage)
• Last Updated: November 2025
• Codebase: Plebeian Market

---

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