mkstackwithwelshman/README.md

MKStack with Welshman

Template for building Nostr client applications with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify - enhanced with Welshman for intelligent relay management.

Overview

This is an enhanced version of the MKStack template that replaces the basic NPool implementation with NWelshman - a more sophisticated relay pool manager that provides intelligent routing, quality scoring, and specialized relay selection.

Key Differences from Base MKStack

1. Enhanced Relay Management

Base MKStack (NPool):

• Simple relay connection using NRelay1
• All queries go to a single configured relay
• Basic round-robin publishing to preset relays
• No distinction between relay types or capabilities

This Template (NWelshman):

• Intelligent relay routing with quality scoring
• Specialized relay selection based on query type:
  • Indexer relays for metadata (kinds 0, 3, 10002)
  • Search relays for NIP-50 full-text search
  • Static relays for general queries
• Quality-based relay prioritization
• Configurable redundancy and connection limits

2. Router Configuration

The NostrProvider now implements a sophisticated Router class that provides:

// Relay selection based on capability
getIndexerRelays()    // Returns relays optimized for metadata
getSearchRelays()      // Returns NIP-50 compatible search relays
getStaticRelays()      // Returns general-purpose relays

// Quality assessment
getRelayQuality(url)   // Returns 0-1 quality score per relay

// Connection management
getRedundancy()        // Number of relays to query (default: 2)
getLimit()            // Maximum relay connections (default: 5)

3. Performance Benefits

• Reduced latency: Queries are sent to relays best suited for the task
• Better reliability: Redundancy ensures queries succeed even if one relay fails
• Optimized bandwidth: Intelligent routing reduces unnecessary connections
• Faster metadata lookups: Dedicated indexer relays for profile data
• Enhanced search: NIP-50 aware relay selection for text search

Dependencies

This template adds the following dependencies to base MKStack:

{
  "@nostrify/welshman": "^0.35.0",
  "@welshman/util": "^0.4.2"
}

Router Implementation

This template includes a custom Router class that bridges the version gap between @welshman/util v0.4.2 and the v0.0.2 interface that NWelshman expects. The implementation provides:

• Full compatibility with NWelshman's routing requirements
• Support for all Router scenario methods (User(), FromPubkeys(), WithinMultipleContexts(), etc.)
• Proper relay selection and quality scoring
• Policy-based fallback handling

Usage

The template maintains full compatibility with the base MKStack API. All existing hooks and components work without modification:

// Works exactly the same as base MKStack
const { nostr } = useNostr();
const events = await nostr.query([{ kinds: [1], limit: 20 }]);

Relay Configuration

The Router automatically categorizes relays based on their known capabilities:

Known Indexer Relays

• wss://relay.nostr.band
• wss://relay.damus.io
• wss://purplepag.es

Known Search Relays (NIP-50)

• wss://relay.nostr.band
• wss://nostr.wine
• wss://search.nos.today

Quality Scoring

Relays are scored from 0.0 to 1.0 based on:

• User's configured relay: 1.0 (highest priority)
• Known high-quality relays: 0.8-0.9
• Preset relays: 0.7
• Unknown relays: 0.5 (lowest priority)

Testing

The template includes comprehensive test coverage:

• Unit tests (NostrProvider.test.tsx): Mock-based testing of router configuration
• Integration tests (NostrProvider.integration.test.tsx): Real relay connection tests

Run tests with:

npm test

Migration from Base MKStack

To migrate an existing MKStack project to use Welshman:

1. Install the new dependencies:

   npm install @nostrify/welshman @welshman/util
   

2. Replace the NostrProvider component with the Welshman version

3. No other code changes required - the API remains the same

When to Use This Template

Choose this Welshman-enhanced template when you need:

• High-performance Nostr apps that benefit from intelligent relay routing
• Apps with heavy metadata queries (profile lookups, contact lists)
• Search functionality using NIP-50
• Better reliability through redundancy
• Production-ready relay management

Use the base MKStack template for:

• Simple prototypes or learning projects
• Apps that only need basic relay connectivity
• Minimal dependency requirements

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Run tests
npm test

License

Same as MKStack base template.