smesh/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Smesh is a React/TypeScript Nostr client for exploring relay feeds. It's a PWA built with Vite, using TailwindCSS for styling and Radix UI/shadcn components.

Development Commands

npm install       # Install dependencies
npm run dev       # Start dev server (Vite, accessible on local network)
npm run dev:8080  # Start dev server on 0.0.0.0:8080 with hot-reload
./hotrefresh      # Kill and restart the dev server on port 8080
npm run build     # TypeScript check + Vite build
npm run lint      # Run ESLint
npm run format    # Run Prettier
npm run preview   # Preview production build

Docker: docker compose up --build -d (serves on localhost:8089)

Architecture

Directory Structure

• src/pages/primary/ - Main tab pages (home, explore, notifications, settings, etc.)
• src/pages/secondary/ - Detail/modal pages (note view, user profile, relay details)
• src/providers/ - React Context providers for state management
• src/services/ - Business logic and external integrations
• src/components/ - Reusable UI components (with ui/ subdirectory for base components)
• src/lib/ - Utility functions
• src/hooks/ - Custom React hooks
• src/routes/ - Route definitions (primary.tsx and secondary.tsx)
• src/i18n/ - Internationalization with i18next

State Management

Uses React Context API with 17+ nested providers in App.tsx. Key providers:

• NostrProvider - Core authentication and signing (supports nsec, NIP-07, NIP-46 bunker, ncryptsec, npub view-only)
• FeedProvider - Active feed state (following, relays, pinned)
• FavoriteRelaysProvider - User's relay sets
• FollowListProvider, MuteListProvider - Social graph

Provider pattern:

const Context = createContext<TContext | undefined>(undefined)
export const useMyFeature = () => {
  const context = useContext(Context)
  if (!context) throw new Error('Must be within provider')
  return context
}

Routing

Custom stack-based navigation in PageManager.tsx:

• Primary pages: Main tabs rendered in left column (desktop) or full screen (mobile)
• Secondary pages: Detail views rendered in right column or as overlay stack
• Uses path-to-regexp for URL matching
• usePrimaryPage() and useSecondaryPage() hooks for navigation

Nostr Integration

• ClientService (src/services/client.service.ts) - Singleton wrapping nostr-tools SimplePool
• Event caching with DataLoader and LRU cache
• User search with FlexSearch index
• IndexedDB storage for events (indexed-db.service.ts)
• localStorage for preferences (local-storage.service.ts)

Key types in src/types/index.d.ts:

• TProfile, TRelayList, TDraftEvent, ISigner

UI Components

• Base components: Radix UI primitives in src/components/ui/
• Rich text editor: Tiptap in src/components/PostEditor/
• Note display: src/components/Note/NoteCard.tsx

Key Patterns

Path Alias

@/ maps to src/ (configured in tsconfig.json and vite.config.ts)

Page Components

Pages use forwardRef to expose scrollToTop method:

const MyPage = forwardRef<TPageRef>((props, ref) => {
  useImperativeHandle(ref, () => ({ scrollToTop: (behavior) => ... }))
})

Event Constants

Nostr event kinds in src/constants.ts:

• Standard kinds from nostr-tools
• Extended kinds in ExtendedKind (polls, pictures, voice notes, etc.)
• Regex patterns for content parsing (URLs, mentions, hashtags, etc.)

Important Files

• src/App.tsx - Provider nesting order matters
• src/PageManager.tsx - Navigation and layout logic
• src/constants.ts - Global constants, relay URLs, storage keys
• src/lib/event.ts - Event parsing utilities