ZapTrax

A decentralized music player and discovery platform built on the Nostr protocol. ZapTrax combines music streaming from Wavlake with social features, Lightning payments, and decentralized playlist management, creating a comprehensive music experience powered by Bitcoin and Nostr.

Features

ZapTrax is a full-featured decentralized music platform with the following capabilities:

🎵 Music Streaming & Discovery

• Wavlake Integration - Stream high-quality music from the Wavlake platform
• Music Search - Discover tracks, artists, and albums
• Top Charts - Browse trending music ranked by Lightning payments
• Artist & Album Pages - Detailed views with complete discographies

🎧 Player Features

• Full Music Player - Play, pause, skip, volume control, and seek functionality
• Queue Management - Add tracks to queue and manage playback order
• Now Playing Status - Broadcast current listening activity (NIP-38)
• Persistent Playback - Music continues across page navigation

📝 Playlist Management

• Create Playlists - Build custom playlists using NIP-51 bookmark sets
• Liked Songs - Automatic "Liked Songs" playlist for favorited tracks
• Share Playlists - Share playlists via Nostr addresses (naddr)
• Edit & Delete - Full playlist management capabilities

💬 Social Features

• Track Comments - Comment on tracks using kind 1 text notes
• Like System - Like tracks and artists with NIP-25 reactions
• Artist Profiles - View artist information and social interactions
• Real-time Engagement - See likes and comments from other users

⚡ Lightning Integration

• Zap Tracks - Send Lightning payments to support artists (NIP-57)
• Zap Artists - Direct artist support through Lightning
• WebLN Support - Seamless payments with WebLN-enabled wallets
• Value-for-Value - Support the music you love with micropayments

🔐 Decentralized Identity

• Nostr Authentication - Login with browser extensions (NIP-07)
• Profile Management - Edit your Nostr profile and metadata
• Multi-Account Support - Switch between multiple Nostr accounts
• Privacy Controls - Control what information you share

🎨 User Experience

• Responsive Design - Optimized for desktop and mobile devices
• Dark/Light Themes - Complete theme system with user preferences
• PWA Support - Install as a progressive web app
• Offline Capabilities - Continue using core features offline

Technology Stack

Frontend

• React 18.x - Modern React with hooks and concurrent rendering
• TypeScript - Type-safe JavaScript development
• TailwindCSS 3.x - Utility-first CSS framework for responsive design
• Vite - Fast build tool and development server
• shadcn/ui - Accessible UI components built with Radix UI

Nostr & Bitcoin Integration

• Nostrify - Nostr protocol framework for web applications
• WebLN - Lightning Network browser integration
• NIP-07 - Browser extension signing for secure authentication
• TanStack Query - Efficient data fetching and caching for Nostr events

Music Platform

• Wavlake API - Music streaming and metadata from Wavlake
• HTML5 Audio - Native browser audio playback capabilities
• React Context - Global music player state management

Routing & State

• React Router - Client-side routing with scroll restoration
• React Context - Application state management
• Local Storage - Persistent user preferences and settings

Quick Start

Prerequisites

• Node.js 18+ and npm
• A Nostr browser extension (recommended: nos2x, Alby, or similar)

Installation

1. Clone the repository

   git clone <repository-url>
   cd zaptrax

2. Install dependencies

   npm install

3. Start development server

   npm run dev

4. Open your browser Navigate to http://localhost:5173

Building for Production

npm run build

The built files will be in the dist/ directory.

Project Structure

src/
├── components/          # React components
│   ├── ui/             # shadcn/ui components (48+ available)
│   ├── auth/           # Authentication components
│   └── ...             # Feature-specific components
├── hooks/              # Custom React hooks
│   ├── useNostr.ts     # Core Nostr integration
│   ├── useAuthor.ts    # Fetch user profiles
│   ├── useCurrentUser.ts # Current user state
│   └── ...             # Additional hooks
├── pages/              # Page components for routing
├── lib/                # Utility functions
├── contexts/           # React context providers
└── test/               # Testing utilities

Key Components

Authentication

import { LoginArea } from "@/components/auth/LoginArea";

function App() {
  return <LoginArea className="max-w-60" />;
}

Profile Management

import { EditProfileForm } from "@/components/EditProfileForm";

function EditProfile() {
  return <EditProfileForm />;
}

Rich Text Content

import { NoteContent } from "@/components/NoteContent";

function Post({ event }) {
  return (
    <div className="whitespace-pre-wrap break-words">
      <NoteContent event={event} className="text-sm" />
    </div>
  );
}

Custom Hooks

Querying Nostr Data

import { useNostr } from '@nostrify/react';
import { useQuery } from '@tanstack/react-query';

function usePosts() {
  const { nostr } = useNostr();

  return useQuery({
    queryKey: ['posts'],
    queryFn: async (c) => {
      const signal = AbortSignal.any([c.signal, AbortSignal.timeout(1500)]);
      const events = await nostr.query([{ kinds: [1], limit: 20 }], { signal });
      return events;
    },
  });
}

Publishing Events

import { useNostrPublish } from '@/hooks/useNostrPublish';
import { useCurrentUser } from '@/hooks/useCurrentUser';

function CreatePost() {
  const { user } = useCurrentUser();
  const { mutate: createEvent } = useNostrPublish();

  const handleSubmit = (content: string) => {
    createEvent({ kind: 1, content });
  };

  // Component implementation...
}

File Uploads

import { useUploadFile } from "@/hooks/useUploadFile";

function FileUploader() {
  const { mutateAsync: uploadFile, isPending } = useUploadFile();

  const handleUpload = async (file: File) => {
    const [[_, url]] = await uploadFile(file);
    // Use the uploaded file URL
  };

  // Component implementation...
}

Configuration

Relay Configuration

The app includes preset relay configurations:

• Nostr.Band (default) - wss://relay.nostr.band
• Ditto - wss://relay.ditto.pub
• Damus - wss://relay.damus.io
• Primal - wss://relay.primal.net

Users can switch relays using the RelaySelector component.

Theme Configuration

Customize themes by modifying CSS custom properties in src/index.css:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  /* ... other theme variables */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... dark theme variables */
}

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run test - Run tests with type checking and linting
• npm run deploy - Build and deploy (requires nostr-deploy-cli setup)

Nostr Protocol Integration

This project follows Nostr protocol standards and best practices:

• NIP-01 - Basic protocol flow
• NIP-07 - Browser extension signing
• NIP-19 - Bech32-encoded entities (npub, note, naddr, etc.)
• NIP-44 - Encryption/decryption
• NIP-94 - File metadata for uploads
• Custom NIPs - Documented in NIP.md when applicable

Event Kinds

The project supports standard Nostr event kinds:

• Kind 0 - User metadata/profiles
• Kind 1 - Text notes/posts
• Kind 3 - Contact lists
• Custom kinds - Application-specific events (documented in NIP.md)

Development Guidelines

Code Style

• Use TypeScript for all new code
• Follow React hooks patterns
• Use shadcn/ui components for UI consistency
• Implement proper loading states (skeletons for content, spinners for actions)
• Handle empty states with relay switching options

Nostr Best Practices

• Always validate events with required tags/content
• Combine queries when possible to avoid rate limiting
• Use single-letter tags (t) for efficient relay filtering
• Prefer existing NIPs over custom kinds for interoperability
• Document custom event schemas in NIP.md

Performance

• Use React Query for efficient data caching
• Implement proper loading and error states
• Optimize queries with appropriate timeouts and limits
• Use skeleton loading for better perceived performance

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm run test
5. Submit a pull request

License

[Add your license information here]

About ZapTrax

ZapTrax is designed to provide a seamless experience for users navigating the Nostr ecosystem. The application focuses on:

• Content Discovery - Advanced algorithms for finding relevant content
• Social Interactions - Enhanced engagement features and community building
• Value Exchange - Lightning integration for micropayments and content monetization
• Privacy & Security - End-to-end encryption and decentralized identity management

Acknowledgments

• Built with MKStack
• Powered by the Nostr protocol
• UI components from shadcn/ui
• Nostr integration via Nostrify

---

For more information about the Nostr protocol, visit nostr.com. Learn more about Lightning payments at lightning.network.