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 using the latest @welshman/util v0.4.2.

Overview

This is an enhanced version of the MKStack template that replaces the basic NPool implementation with NWelshman - a sophisticated relay pool manager that provides intelligent routing, quality scoring, and specialized relay selection. This template has been fully updated to use the modern @welshman/util v0.4.2 implementation without any compatibility layers.

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"
}

Modern Router Implementation

This template uses the complete modern Router implementation from the Welshman repository, fully compatible with @welshman/util v0.4.2. The implementation provides:

• Native v0.4.2 compatibility - No compatibility layers needed
• Complete Router functionality - All routing scenarios supported (User(), FromPubkeys(), WithinMultipleContexts(), etc.)
• Enhanced address handling - Full support for community and group contexts
• Advanced relay selection - Quality scoring, redundancy, and policy-based fallbacks
• Modern event utilities - Complete Events API with type guards, conversions, and relationship 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 with 100% pass rate:

• Router tests (Router.test.ts): Complete Router functionality validation (4 tests)
• Events tests (Events.test.ts): Full @welshman/util v0.4.2 Events API testing (28 tests)
• Address tests (Address.test.ts): Addressable event handling validation (20 tests)
• Encryptable tests (Encryptable.test.ts): Encryption/decryption functionality (11 tests)
• Filters tests (Filters.test.ts): Query optimization and matching (26 tests)
• Handler tests (Handler.test.ts): NIP-89 application handlers (15 tests)
• List tests (List.test.ts): Public/private list management (24 tests)
• Profile tests (Profile.test.ts): User profile management (22 tests)
• Tags tests (Tags.test.ts): Tag parsing and validation (16 tests)
• Zaps tests (Zaps.test.ts): Lightning Network integration (20 tests)
• Component tests (NostrProvider.test.tsx): Mock-based router configuration testing
• Integration tests (NostrProvider.integration.test.tsx): Real relay streaming functionality
• Additional tests: Error boundaries, content rendering, utility functions

Test Results:

• ✅ 203/203 tests passing (100%)
• ✅ TypeScript compilation passes
• ✅ ESLint passes
• ✅ Production build succeeds

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

Features & Capabilities

This template provides production-ready Nostr client functionality:

✅ Modern Architecture

• @welshman/util v0.4.2 - Latest Welshman utilities with full feature set
• Zero compatibility layers - Direct usage of modern APIs
• Complete Events API - Type guards, conversions, event relationships
• Advanced Router - All routing scenarios with context awareness

✅ Intelligent Relay Management

• Quality-based routing - Automatic relay scoring and selection
• Specialized relay types - Indexer, search, and general-purpose relays
• Redundancy support - Configurable connection redundancy for reliability
• Context-aware routing - Community (NIP-72) and Group (NIP-29) support

✅ Complete Nostr API Coverage

• Router - Intelligent relay selection and routing (4 tests)
• Events - Event creation, validation, and relationships (28 tests)
• Address - Addressable event handling (20 tests)
• Encryptable - Encryption/decryption for private content (11 tests)
• Filters - Query optimization and matching (26 tests)
• Handler - NIP-89 application handlers (15 tests)
• List - Public/private list management (24 tests)
• Profile - User profile management (22 tests)
• Tags - Tag parsing and validation (16 tests)
• Zaps - Lightning Network integration (20 tests)

✅ Developer Experience

• 100% test coverage - Comprehensive test suite with 203/203 tests passing
• TypeScript ready - Full type safety with modern Welshman types
• Easy migration - Drop-in replacement for basic relay pools
• Production ready - Complete Nostr development framework

✅ When to Use This Template

• Production Nostr applications requiring robust relay management
• Lightning-enabled apps with zaps and payments
• Social applications with profiles, lists, and communities
• High-performance apps with heavy metadata or search requirements
• Community/group-aware applications using NIP-29 or NIP-72
• Apps requiring reliability through intelligent relay redundancy

Use simpler alternatives for basic prototypes or minimal relay connectivity needs.

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.