Hono Server + Turso (Libsql) + Lucia Auth + Drizzle ORM Ultra-Low Latency Engine — CLAUDE.md Template

Overview

This CLAUDE.md template provides a copyable CLAUDE.md blueprint for building ultra-low latency edge APIs using Hono Server, Turso LibSQL, Lucia Auth, and Drizzle ORM. It is tailored for Claude Code to produce a production-ready skeleton that can be pasted directly into a CLAUDE.md file and refined into a fully functioning codebase.

When to Use This CLAUDE.md Template

• You are architecting an edge API with near-zero latency requirements.
• You want a cohesive stack combining Hono on the edge, LibSQL through Turso, Lucia authentication, and Drizzle ORM for type-safe DB access.
• You need a reproducible CLAUDE.md template that yields a maintainable project structure and robust security defaults.
• You require clear constraints Claude Code should follow to avoid architectural drift.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code. Your task is to generate a copyable CLAUDE.md template for the Hono + Turso LibSQL + Lucia Auth + Drizzle ORM stack that a developer can paste directly into CLAUDE.md and run to scaffold the project.

Architecture rules:
- Edge-first: Hono server handles routes at the edge with minimal cold-start.
- DB layer: Turso LibSQL (remote LibSQL) accessed via Drizzle ORM with a small query surface.
- Auth: Lucia Auth with cookie-based sessions, properly secured cookies, and server-side session validation.
- ORM: Drizzle ORM for type-safe queries and migrations against LibSQL schema.
- Language/runtime: TypeScript, ESM modules, aligned with Hono’s runtime expectations.
- Observability: Lightweight logging and error handling suitable for edge latency budgets.
- Separation of concerns: auth, routes, DB schema, and config are clearly separated.

File structure rules:
- src/server.ts
- src/routes/
  - index.ts
  - api.ts
  - auth.ts
- src/db/
  - drizzle.ts
  - schema.ts
  - migrations/
- src/auth/
  - lucia.ts
- src/lib/
  - turbodb.ts
- config/
  - env.example
- README.md

Authentication rules:
- Use Lucia Auth with cookie-based sessions and HttpOnly cookies.
- Sessions should be signed and have appropriate maxAge values.
- Do not store plaintext passwords; use proper password hashing (argon2 or bcrypt).
- Protect sensitive routes with auth middleware.

Database rules:
- Use Turso LibSQL for the underlying database and connect with Drizzle ORM.
- Define a minimal users table and a sessions table compatible with Lucia.
- Migrations should be deterministic and idempotent.
- Do not expose raw SQL strings to the client; use Drizzle query builder.

Validation rules:
- Validate all inputs on the server using a strict schema (e.g., zod) before hitting DB or auth.
- Normalize inputs (trim, lower-case emails) where appropriate.
- Provide meaningful error messages for validation failures.

Security rules:
- Do not log sensitive credentials.
- Use HTTPS in all environments; set HttpOnly, Secure, SameSite cookies.
- Validate tokens and enforce CSRF protection for state-changing requests.
- Avoid any SQL injection surface by using Drizzle’s query builder.

Testing rules:
- Unit tests for validation and business logic using Vitest.
- Integration tests for auth flows and DB interactions.
- End-to-end checks for critical routes; keep tests deterministic.

Deployment rules:
- Migrate DB on deploy using a migration runner.
- Secrets and DB connection strings come from environment variables, not hard-coded.
- Build and ship a small bundle suitable for edge runtimes; minimize bundle size.
- Rollback plan for failed deployments.

Things Claude must not do:
- Do not generate Prisma, Mongoose, or other non-Drizzle ORMs for this stack.
- Do not assume a relational model that contradicts LibSQL capabilities.
- Do not export DB credentials to client-side code.
- Do not ignore edge constraints; assume higher latency budgets are not available.

Recommended Project Structure

/apps/hono-edge
  /src
    main.ts
    /routes
      index.ts
      api.ts
      auth.ts
    /middleware
      auth.ts
    /db
      drizzle.ts
      schema.ts
      /migrations
        20240501_init.ts
    /auth
      lucia.ts
    /lib
      turbodb.ts
  /config
    env.example
  /scripts
    migrate.ts

Core Engineering Principles

• Latency-first design: minimize async boundaries and cold-starts.
• Explicit contracts: clear interfaces between layers (auth, DB, routes).
• Type-safety: rely on Drizzle typings and Zod schemas to prevent runtime errors.
• Security by default: sane default values, strict input validation, and secure cookies.
• Observability: lightweight telemetry to identify bottlenecks at the edge.

Code Construction Rules

• Use TypeScript-first approach with strict type checks.
• Model DB tables with Drizzle ORM and keep migrations deterministic.
• Configure Lucia Auth with cookie-based sessions and secure cookies.
• All APIs should use Hono route handlers with dependency-injected DB and auth layers.
• Validate all request bodies with a strict schema before DB access.
• Do not hard-code secrets; rely on environment variables.
• Do not mix SQL queries with string interpolation; use Drizzle's query builder.
• Use descriptive error handling and avoid leaking stack traces to clients.

Security and Production Rules

• Enable TLS in all environments and enforce Secure cookies.
• Enforce SameSite policy and HttpOnly for session cookies.
• Regularly rotate keys and secret salts used by Lucia and the app.
• Limit request sizes and implement rate limiting on critical routes.
• Audit dependencies for known vulnerabilities and update promptly.

Testing Checklist

• Unit tests for validation and small utility functions.
• Integration tests for auth flows (login, signup) and DB access through Drizzle.
• End-to-end tests for critical edge routes using a lightweight test harness.
• Migration tests to ensure schema compatibility across environments.
• Performance checks to ensure latency remains within target budgets.

Common Mistakes to Avoid

• Assuming Prisma or Mongoose can be used with Turso LibSQL; stick to Drizzle ORM.
• Exposing DB credentials or tokens to the client.
• Ignoring edge-runtime constraints and creating heavy monolith components.
• Overcomplicating the authentication flow beyond Lucia’s recommended usage.

FAQ

• What is this CLAUDE.md Template for?
  A copyable CLAUDE.md template for building an ultra-low latency Hono + Turso LibSQL + Lucia Auth + Drizzle ORM stack.
• Which components are involved?
  Hono server, Turso LibSQL, Lucia Auth, Drizzle ORM.
• Can I adapt this template to other stacks?
  Yes, but adjust the Claude Code instructions to reflect the new components and constraints.
• Where can I find more CLAUDE.md Templates?
  In the CLAUDE.md Templates collection under AI Skills on Suhas Bhairav's site.
• How do I validate inputs?
  Use strict server-side schemas (e.g., Zod) before DB or auth operations.