CLAUDE.md Template: Next.js 16 + Turso (Edge LibSQL) + Lucia Auth + Drizzle ORM Starter

Overview

A CLAUDE.md template for a Next.js 16 starter leveraging Turso Edge LibSQL, Lucia Auth, and Drizzle ORM. This page helps engineers quickly scaffold a secure, scalable edge-ready application with a coherent architecture and Claude Code guidance.

Direct answer: This CLAUDE.md Template provides a ready-to-use blueprint for a Next.js 16 app with Turso LibSQL edge database, Lucia authentication, and Drizzle ORM, including a copyable CLAUDE.md block and stack-specific practices.

When to Use This CLAUDE.md Template

• When creating a Next.js 16 app with App Router and edge data access (Turso LibSQL).
• When you need authentication managed by Lucia for both SSR and API routes.
• When your data layer uses Drizzle ORM with a LibSQL-compatible database.
• When you want a repeatable starter that enforces security, validation, and deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Lead Full-Stack Engineer for a Next.js 16 starter with Turso Edge LibSQL, Lucia Auth, and Drizzle ORM.

Architecture rules:
- Use Next.js 16 App Router with server components where appropriate.
- Edge computations should be stateless; store mutable state in LibSQL via Drizzle ORM.
- Centralize config in environment variables; do not hardcode secrets.
- Separate concerns: auth, data access, and business logic in distinct modules.

File structure rules:
- Follow a conventional monorepo layout:
  - apps/web/
  - packages/db/
  - packages/auth/
  - packages/orm/
- Avoid creating folders outside the defined stack boundaries.

Authentication rules:
- Use Lucia Auth with a database adapter for LibSQL.
- Email/password and social providers optional; keep secrets in env vars.
- Protect API routes with middleware that validates sessions.

Database rules:
- Use Turso LibSQL in edge mode; migrations under packages/db/migrations.
- Drizzle ORM models must be generated from schema.ts and kept in packages/orm.
- Never expose connection strings in client code.

Validation rules:
- Validate API inputs with Zod schemas in server components.
- Return 400 for invalid payloads; surface helpful, non-sensitive error messages.

Security rules:
- Implement CSP, X-Frame-Options, and strict transport security in headers.
- Do not log full request bodies in production.
- Rotate keys via CI/CD and update env vars without downtime.

Testing rules:
- Unit test business logic with Vitest.
- Integration tests for API routes with Playwright or Cypress.
- E2E tests should cover login flow and protected data access.

Deployment rules:
- Deploy to a platform that supports edge runtimes; configure Turso LibSQL and environment secrets.
- Use CI to run tests and lint; cache dependencies for faster pipelines.

Things Claude must not do:
- Do not embed private keys or database credentials in code.
- Do not bypass auth checks in API routes.
- Do not generate tooling that relies on deprecated APIs.

Recommended Project Structure

apps/web/                 # Next.js 16 App Router application
  app/
    layout.tsx
    page.tsx
  pages/
    api/
      auth/[...].ts
  next.config.js
  tsconfig.json
packages/db/              # LibSQL and Drizzle integration
  libsql.ts              # Turso LibSQL client (edge)
  migrations/
  drizzle.ts             # Drizzle ORM setup for LibSQL
packages/auth/            # Lucia Auth configuration
  lucia.ts
  providers/
packages/orm/             # Drizzle ORM models and migrations
  schema.ts
  migrations/
  drizzle-setup.ts
.env.example

Core Engineering Principles

• Security by default: encrypt secrets, validate inputs, and restrict data exposure.
• Edge-first design: minimize latency with edge data access via Turso LibSQL.
• Type safety: use Drizzle ORM schemas and Zod validations end-to-end.
• Explicit boundaries: separate auth, data access, and UI logic.
• Observability: structured logs, tracing, and metrics for API routes.

Code Construction Rules

• Next.js 16 App Router is the foundation; avoid mixing old pages directory patterns unless necessary.
• Use Turso LibSQL edge database and ensure migrations live under packages/db/migrations.
• Lucia Auth must be configured with a LibSQL adapter; sessions stored securely server-side.
• Drizzle ORM models should map to LibSQL tables via a single source of truth in packages/orm/schema.ts.
• All API routes should be stateless and rely on getServerSession or middleware for auth checks.
• Environment-based configuration only; never fabricate credentials in code.
• All database queries must be typed; prefer Drizzle query builder over raw SQL strings in app code.

Security and Production Rules

• Store secrets in environment variables and CI/CD vaults; never commit keys.
• Implement CSP and strict transport security headers; enable proper content isolation.
• Protect API routes with middleware checks for valid sessions and roles where applicable.
• Enable database access restrictions and row-level security where possible on LibSQL.
• Regularly rotate signing keys and invalidate old sessions as part of deployment.

Testing Checklist

• Unit tests for business logic with Vitest; mock DB when possible.
• Integration tests for API routes using a mock or in-memory LibSQL instance.
• End-to-end tests for login flow and protected resources using Playwright.
• CI should run lint, type checks, unit tests, and limited integration tests on push.

Common Mistakes to Avoid

• Hardcoding secrets or database connection strings in code or repo.
• Relying on client-side data for authentication decisions; always verify server-side.
• Overexposing APIs; ensure proper authorization for all endpoints.
• Skipping migrations or mismatching Drizzle schemas with LibSQL tables.

FAQ

Q: What is the target stack for this CLAUDE.md Template?

A: Next.js 16 App Router, Turso Edge LibSQL, Lucia Auth, and Drizzle ORM.

Q: Can I swap Turso LibSQL with another LibSQL-compatible DB?

A: Yes, but update the LibSQL client and Drizzle adapters accordingly and adjust migrations.

Q: How do I test edge data access?

A: Write integration tests that exercise API routes against a LibSQL instance in a test environment.

Q: Where should secrets live in CI/CD?

A: In a dedicated secrets vault or CI/CD secret store; reference via environment variables at runtime.