nontara
8fecd89d8f
This new file provides comprehensive guidance for developers using warp.dev, covering project overview, development commands, architecture, configuration details, and troubleshooting tips for the monorepo.
153 lines
4.9 KiB
Markdown
153 lines
4.9 KiB
Markdown
# WARP.md
|
|
|
|
This file provides guidance to WARP (warp.dev) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Nontara is an alternative to Jellyfin designed to provide private media streaming services. It's a TypeScript-based monorepo built with:
|
|
|
|
- **Bun**: Runtime environment and package manager
|
|
- **Turborepo**: Monorepo build system
|
|
- **TanStack Start**: SSR framework for the frontend
|
|
- **Hono**: Backend server framework
|
|
- **tRPC**: Type-safe APIs
|
|
- **Drizzle**: TypeScript-first ORM with SQLite
|
|
- **Better-Auth**: Authentication system
|
|
- **Biome**: Code formatting and linting
|
|
|
|
## Development Commands
|
|
|
|
### Core Development
|
|
```bash
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Run all applications in development
|
|
bun dev
|
|
|
|
# Run specific applications
|
|
bun dev:web # Frontend only (localhost:3001)
|
|
bun dev:server # Backend only (localhost:3000)
|
|
|
|
# Build all applications
|
|
bun build
|
|
```
|
|
|
|
### Database Operations
|
|
```bash
|
|
# Start local SQLite database (run from project root)
|
|
cd apps/server && bun db:local
|
|
|
|
# Push schema changes to database
|
|
bun db:push
|
|
|
|
# Open database studio UI
|
|
bun db:studio
|
|
|
|
# Generate migrations
|
|
bun db:generate
|
|
|
|
# Run migrations
|
|
bun db:migrate
|
|
```
|
|
|
|
### Code Quality
|
|
```bash
|
|
# Run Biome formatting and linting
|
|
bun check
|
|
|
|
# Check TypeScript types across all apps
|
|
bun check-types
|
|
```
|
|
|
|
### Testing and Single File Operations
|
|
```bash
|
|
# Run a specific test file (from workspace root)
|
|
cd packages/language-codes && bun test.ts
|
|
|
|
# Check types for specific app
|
|
cd apps/server && bun run check-types
|
|
cd apps/web && bun run check-types
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
### Monorepo Structure
|
|
- `apps/web/` - React frontend with TanStack Start (SSR)
|
|
- `apps/server/` - Hono backend with tRPC API layer
|
|
- `packages/language-codes/` - Shared language utilities
|
|
- `extensions/tmdb-metadata/` - TMDB metadata provider extension
|
|
|
|
### Backend Architecture (apps/server)
|
|
|
|
**Service Container Pattern**: The server uses a dependency injection container that manages service lifecycle:
|
|
- `Service` class implements the container with registration, activation, and graceful shutdown
|
|
- All services extend `BaseService` and implement `IMountable`/`IDisposable`
|
|
- Services: OnboardService, ExtensionService, MetadataService, LibraryScannerService
|
|
|
|
**API Layer**:
|
|
- **Hono**: HTTP framework handling CORS, logging, auth endpoints
|
|
- **tRPC**: Type-safe API with three procedure types:
|
|
- `publicProcedure`: No authentication required
|
|
- `protectedProcedure`: Requires valid session
|
|
- `onboardProcedure`: Special procedure for initial setup
|
|
|
|
**Data Layer**:
|
|
- **Drizzle ORM**: Type-safe database operations with SQLite
|
|
- **Better-Auth**: Authentication with session management
|
|
- Database schema in `src/db/schema/`
|
|
|
|
### Frontend Architecture (apps/web)
|
|
|
|
**Routing & State**:
|
|
- **TanStack Router**: File-based routing with type-safe navigation
|
|
- **TanStack Query**: Server state management with tRPC integration
|
|
- Route tree auto-generated in `routeTree.gen.ts`
|
|
|
|
**Component Architecture**:
|
|
- **shadcn/ui**: Reusable component library
|
|
- **TailwindCSS**: Utility-first styling with custom configuration
|
|
- **Radix UI**: Headless component primitives
|
|
|
|
### Key Patterns
|
|
|
|
**Type Safety**: End-to-end TypeScript from database schema to frontend components via tRPC
|
|
|
|
**Workspace Dependencies**: Uses `workspace:*` protocol for internal package references
|
|
|
|
**Extension System**: Modular extension architecture for metadata providers and other plugins
|
|
|
|
## Important Configuration Details
|
|
|
|
### Environment Setup
|
|
Both `apps/server/` and `apps/web/` have `.env.example` files that need to be copied to `.env` and configured.
|
|
|
|
### Database Configuration
|
|
- SQLite database with Drizzle migrations in `apps/server/src/db/migrations/`
|
|
- Schema definitions in `apps/server/src/db/schema/`
|
|
- Use `turso dev --db-file local.db` for local development database
|
|
|
|
### Code Style
|
|
- **Biome**: Enforces tab indentation, double quotes, and organized imports
|
|
- **TailwindCSS**: Classes sorted with custom functions (clsx, cva, cn)
|
|
- **TypeScript**: Strict type checking across all packages
|
|
|
|
### Extension Development
|
|
Extensions follow the pattern established in `extensions/tmdb-metadata/`:
|
|
- Must implement the service interface pattern
|
|
- Should be workspace packages with proper TypeScript configuration
|
|
- Can depend on the server workspace for shared types and utilities
|
|
|
|
## Troubleshooting
|
|
|
|
### Service Container Issues
|
|
If services fail to start, check the service activation order in `apps/server/src/services/setup/index.ts`. Services are activated sequentially and have automatic rollback on failure.
|
|
|
|
### Database Issues
|
|
- Ensure `cd apps/server && bun db:local` is running before starting the server
|
|
- Use `bun db:push` to sync schema changes
|
|
- Check `drizzle.config.ts` for database connection configuration
|
|
|
|
### Type Errors
|
|
- Run `bun check-types` to see all TypeScript errors across the monorepo
|
|
- Ensure route tree is up-to-date by restarting the dev server if routing types are incorrect |