3.4 KiB
3.4 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
Photon is a Svelte-based Lemmy client built with SvelteKit 2 and Svelte 5. It's a modern frontend for Lemmy instances with extensive customization options and multi-platform support.
Key Technologies
- Frontend: SvelteKit 2 + Svelte 5 with TypeScript
- Styling: TailwindCSS v4 + PostCSS
- Desktop App: Tauri (optional, in src-tauri/)
- Package Manager: Bun (primary) or npm
- Build Adapters: Supports Bun, Node, and static builds
Development Commands
Development
# Start development server
bun run dev
# or
npm run dev
Building
# Build for Bun runtime (fastest)
ADAPTER=bun bun run build
# Build for Node runtime (better compatibility)
ADAPTER=node npm run build
# Build static files
ADAPTER=static npm run build
Code Quality
# Type checking
bun run check
# or watch mode
bun run check:watch
# Linting
bun run lint
# Formatting
bun run format
# or specific files
bun run format:specific <file>
Running Built Application
# Start Bun server
bun run bunstart
# Start Node server
bun run start
Testing
The project uses Vitest as configured in package.json, but no test files currently exist:
bun run test
Architecture
Core Structure
- Routes: SvelteKit file-based routing in
src/routes/ - Components: Organized by domain in
src/lib/components/lemmy/: Lemmy-specific components (posts, comments, communities)ui/: Generic UI componentsmono/: Design system components (imported as 'mono-svelte')
- State Management: Svelte 5 runes with custom stores for global state
- Internationalization: Custom i18n system in
src/lib/i18n/
Key Global State
- Authentication:
src/lib/auth.svelte.ts- Profile and user management - Settings:
src/lib/settings.svelte.ts- User preferences and configuration - Lemmy Client:
src/lib/lemmy.svelte.ts- API client and site data - Instance:
src/lib/instance.svelte.ts- Instance URL management
Component Organization
- Lemmy Domain: Components for posts, comments, communities, moderation
- UI Components: Reusable interface elements with design system
- Layout: Shell, navbar, sidebar structure
- Form Components: Input controls with consistent styling
Environment Configuration
Photon uses PUBLIC_ prefixed environment variables for client-side configuration. Default values are defined in src/lib/settings.svelte.ts. Key configuration includes:
PUBLIC_INSTANCE_URL: Default Lemmy instancePUBLIC_SSR_ENABLED: Server-side rendering togglePUBLIC_LOCK_TO_INSTANCE: Whether to allow instance switching
Multi-Platform Support
- Web: Primary SvelteKit application
- Desktop: Optional Tauri wrapper in
src-tauri/for native desktop app - Mobile: PWA capabilities with responsive design
Build System
- Vite: Primary build tool with SvelteKit integration
- Adapters: Dynamic adapter selection via ADAPTER environment variable
- Aliases: 'mono-svelte' points to internal design system at
src/lib/mono
State Patterns
The codebase uses Svelte 5 runes extensively:
$state()for reactive state$derived()for computed values$effect()for side effects- Custom classes with reactive properties for complex state management