Remix Monorepo + SQLite (Litestream Backup) + Lucia Auth + Drizzle ORM Setup | CLAUDE.md Template

Overview

A CLAUDE.md template for a Remix monorepo setup that uses SQLite with Litestream for backup, Lucia Auth for authentication, and Drizzle ORM for data access. This page provides a complete copyable CLAUDE.md instruction block you can paste into a CLAUDE.md file to bootstrap a reproducible development stack.

When to Use This CLAUDE.md Template

• You are starting a Remix monorepo with a zero-to-one backend-first approach.
• You want SQLite with reliable backups via Litestream in a simple dev-prod parity scenario.
• You need an authentication layer using Lucia Auth integrated with Remix loaders/actions.
• You plan to use Drizzle ORM for type-safe database access and migrations against SQLite.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code tasked with generating a Remix monorepo scaffold using SQLite + Litestream backups, Lucia Auth, and Drizzle ORM. Output must be a complete, ready-to-paste setup including config files, example migrations, and example UI hooks.

Architecture rules:
- Single monorepo layout: apps/ web frontend, packages/ backend modules (db/schema), litestream for backup, and scripts/automation.
- Use TypeScript throughout the stack.
- Prefer small, composable packages with clear boundaries.
- All secrets must be referenced via environment variables or secret managers; never inline secrets.

File structure rules:
- apps/web/                 Remix app workspace
- packages/db/                Drizzle ORM + SQLite setup
- packages/db/src/schema.ts    Drizzle schema definitions
- packages/db/migrations/      Drizzle migrations
- litestream/                 Litestream config and binaries
- litestream.yml              Backup configuration for SQLite
- tools/                      helper scripts and CI shortcuts

Authentication rules:
- Lucia Auth integrated with Remix loaders/actions
- Use cookies with httpOnly, secure flags in production
- Sessions stored in encrypted cookies with a short TTL and rotation
- Passwords hashed with Argon2 or bcrypt, never plain text

Database rules:
- SQLite database file at db/data.sqlite
- Drizzle migrations under packages/db/migrations
- Use Drizzle config at packages/db/src/drizzle.config.ts or similar
- Do not access the database from client-side code directly; use server-side loaders/actions

Validation rules:
- Validate inputs on server and client where applicable
- Use a schema library (e.g., zod) for runtime validation

Security rules:
- Do not log secrets or database URLs in logs
- Do not expose DB files in client bundles
- Use CSRF protection for mutations
- Rotate session keys periodically

Testing rules:
- Unit tests for DB layer using a temporary SQLite database
- Integration tests for Lucia auth flow
- End-to-end tests covering common user journeys

Deployment rules:
- Use a containerized runtime or serverless function with environment variables for secrets
- Provision Litestream backups on the same host as SQLite with proper file permissions
- Run migrations as part of CI before deployment

Things Claude must not do:
- Do not assume network access during generation unless necessary for templates
- Do not output Prisma, Mongoose, or other ORMs not in scope
- Do not render screenshots or images in the template

Recommended Project Structure

monorepo/
├─ apps/
│  └─ web/                    # Remix app
├─ packages/
│  ├─ db/                     # Drizzle ORM + SQLite
│  │  ├─ src/
│  │  │  ├─ drizzle.config.ts
│  │  │  ├─ schema.ts
│  │  │  └─ migrations/
│  │  └─ db.sqlite
│  ├─ lucia/                   # Lucia auth setup (helper utilities)
│  │  ├─ auth.server.ts
│  │  └─ user.ts
│  └─ drizzle/                 # shared Drizzle utilities
│     └─ index.ts
└─ litestream/
   └─ litestream.yml           # backup configuration for SQLite

Core Engineering Principles

• Type-safe end-to-end: TypeScript throughout, with Drizzle types inferred in code.
• Explicit boundaries: Clear server vs client responsibilities, no direct DB access from browser.
• Migration-first: Drizzle migrations tracked in migrations/ with deterministic IDs.
• Reproducible builds: Lockfile-based dependency management, consistent tooling across environments.
• Security-first by default: Secure cookies, CSRF protection, and secret management.

Code Construction Rules

• Use Remix Loader/Action to fetch and mutate data; validation occurs server-side.
• Define Drizzle schema in a single source of truth and generate migrations from it.
• Keep Litestream config outside of client bundles; run Litestream in deployment alongside SQLite.
• Auth flows go through Lucia; guard routes with middleware and loader checks.
• Do not embed database credentials in code; use environment variables.

Security and Production Rules

• Encrypt sensitive data in transit and at rest; prefer secured cookies with httpOnly flag.
• Limit DB surface area from client; use server-only APIs for sensitive actions.
• Rotate signing keys and maintain a rotation plan for sessions.
• Enable Litestream backups and test restores regularly in staging.

Testing Checklist

• Unit tests for Drizzle models and query builders.
• Integration tests for Lucia auth flow (signup, login, session management).
• End-to-end tests for common routes using Remix test environment.
• Migration tests to ensure deterministic SQL generation.
• CI should run migrations, unit tests, and basic lint checks on PRs.

Common Mistakes to Avoid

• Forgetting to isolate client and server DB access.
• Omitting Litestream restore tests or backups in CI.
• Storing secrets in source code or logs.
• Over-optimizing with unnecessary ORM complexity; keep Drizzle simple.

FAQ