nontara/WARP.md

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

# 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

# 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

# Run Biome formatting and linting
bun check

# Check TypeScript types across all apps
bun check-types

Testing and Single File Operations

# 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