Remix + Turso LibSQL + Custom HttpOnly Cookie Auth + Drizzle ORM - CLAUDE.md Template

Overview

A CLAUDE.md template for Remix Framework + Turso LibSQL + Drizzle ORM with Custom HttpOnly Cookie Authentication. This page provides a full, copyable CLAUDE.md template block you can paste into a CLAUDE.md file, plus stack-specific guidance to implement a secure session flow in a Remix app backed by Turso LibSQL and Drizzle ORM. It also presents a concrete project structure and engineering principles tailored to this stack. Direct answer: Use this template to generate a secure, maintainable Remix app with LibSQL storage and type-safe queries via Drizzle, governed by HttpOnly cookie auth, all described in Claude Code.

When to Use This CLAUDE.md Template

• You are building a Remix app with server-side rendering and want a secure HttpOnly cookie-based authentication flow.
• You choose Turso LibSQL as your database with Drizzle ORM for type-safe queries and migrations.
• You need a copyable Claude Code block you can paste into CLAUDE.md to bootstrap architecture, file structure, and security rules.
• You want stack-specific guidance on testing, deployment, and production hardening for this exact combination.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are the Remix + Turso LibSQL + Drizzle ORM specialist responsible for implementing a secure HttpOnly cookie authentication flow and a clean, maintainable codebase.

Architecture rules:
- Use Remix App Router with server-side routes for auth and protected sections.
- Use Turso LibSQL as the primary database layer and Drizzle ORM for type-safe queries and migrations.
- Store session state in an HttpOnly, Secure, SameSite=Strict cookie; never expose tokens to the client.
- All server-side logic must be isolated to server modules; avoid leaking secrets to the client.
- Do not couple business logic to HTTP transport; use clear service boundaries.

File structure rules:
- Place server and DB logic under dedicated folders (lib/, drizzle/, db/).
- Place UI routes under app/routes, components under app/components, and shared utilities under lib/
- Migrations live in drizzle/migrations and are executed via drizzle-kit.

Authentication rules:
- Sessions are stored in an HttpOnly cookie named SESSION_ID.
- Cookie attributes: Secure, HttpOnly, SameSite=Strict, maxAge aligned with session timeout.
- Passwords stored as bcrypt hashes; verify on login.
- Use a server-side session store linked to Turso LibSQL via Drizzle.

Database rules:
- Turso LibSQL used with Drizzle ORM; migrations generated via drizzle-kit and applied on startup in development and CI in production.
- All user credentials stored in a users table with hashed_password, email unique, and created_at/updated_at timestamps.
- No direct SQL construction with string interpolation; use Drizzle query builder.

Validation rules:
- Validate all inputs with a server-side validator (e.g., Zod) in action handlers.
- Normalize and trim inputs; enforce email format and password strength on server side.
- Return structured errors with field-specific feedback (no stack traces to clients).

Security rules:
- Do not store tokens in localStorage; do not expose DB credentials to the frontend.
- Use TLS everywhere; enable CSRF protection where cookies are not enough (but prefer SameSite=Strict with HttpOnly cookies).
- Restrict DB user privileges to the minimum needed for app functionality.
- Regularly rotate session secrets and enforce environment-based configuration.

Testing rules:
- Unit tests for auth logic (password hashing, cookie creation) and for Drizzle-based migrations.
- Integration tests for login, protected routes, and logout using a simulated Remix server.
- CI should run database migrations and basic end-to-end tests.

Deployment rules:
- Build with Remix, generate a server bundle, and deploy to a host that supports Node.js and TLS.
- Configure environment variables for DB_URL, SESSION_SECRET, and TURSO_API_KEY in CI/CD.
- Ensure migrations run on startup in production or as part of the deploy pipeline.

Things Claude must not do:
- Do not generate frontend secrets or hard-code credentials.
- Do not bypass server-side validation or rely on client-side checks for security.
- Do not implement non HttpOnly cookies for session management.
- Do not skip migrations or access the DB outside Drizzle.
- Do not expose raw database error messages to users.

Recommended Project Structure

my-remix-app/
├── app/
│   ├── entry.client.tsx
│   ├── entry.server.tsx
│   ├── root.jsx
│   ├── routes/
│   │   ├── auth/
│   │   │   ├── login.tsx
│   │   │   └── logout.tsx
│   │   └── dashboard.tsx
│   ├── components/
│   │   └── Layout.tsx
│   └── styles/
├── drizzle/
│   ├── client.ts
│   ├── migrations/
│   └── schema.ts
├── lib/
│   ├── db.ts
│   ├── auth.ts
│   ├── session.ts
│   └── validators.ts
├── server/
│   └── index.ts
└── .env.example

Core Engineering Principles

• Explicit contracts between modules; minimize implicit dependencies.
• Type-safety with Drizzle and TypeScript across DB and service layers.
• Idempotent migrations and deterministic build/test pipelines.
• Security-first defaults: HttpOnly cookies, TLS, and minimal DB privileges.
• Clear separation of concerns between UI routes and server/auth logic.
• Testability: structure encourages unit, integration, and CI-ready tests.

Code Construction Rules

• Use Drizzle ORM for all DB access; never write raw SQL with interpolated values.
• Authenticate users with a bcrypt-hashed password stored in LibSQL; compare on login.
• Session management must use an HttpOnly, Secure cookie with SameSite=Strict.
• All inputs are validated server-side with a strict schema (e.g., Zod).
• Frontend should never access secrets or DB credentials; pass only sanitized data to the client.
• End-to-end flows (login, access, logout) must be covered by tests and migrations.
• Do not hard-code secrets; use environment variables injected by the deployment pipeline.

Security and Production Rules

• Use HttpOnly cookies for sessions; set Secure and SameSite=Strict in all environments.
• Store only hashed passwords; never log raw credentials.
• Limit DB user privileges; rotate credentials; monitor for unusual DB access patterns.
• Enable TLS termination at the edge; ensure all internal calls use TLS as well.
• Guard against common web threats: CSRF where needed, input validation, and proper error handling.

Testing Checklist

• Unit tests for auth.ts (hashing, cookie creation) and validators.ts.
• Integration tests for login/logout flows and protected routes using a test DB instance.
• Migrations tests to ensure schema compatibility across environments.
• CI runs: lint, tests, migrations, and a minimal end-to-end check.
• Deployment validation: smoke tests post-deploy to confirm auth and data access work.

Common Mistakes to Avoid

• Storing session tokens in localStorage or exposing them to the frontend.
• Using raw SQL or string interpolation for user inputs.
• Overexposing DB credentials in frontend bundles or logs.
• Neglecting migrations, leading to schema drift between environments.
• Disabling security headers or cookies in production for convenience.

FAQ

Q: What is this CLAUDE.md Template for Remix + Turso LibSQL + Drizzle?

A: It provides a copyable Claude Code blueprint to implement a secure HttpOnly cookie auth flow with a Drizzle-based data model backed by Turso LibSQL in a Remix app.

Q: How do I configure HttpOnly cookie authentication in this template?

A: The CLAUDE.md template specifies an HttpOnly, Secure, SameSite=Strict session cookie named SESSION_ID and a server-side session store bound to Drizzle.

Q: How does Drizzle integrate with Turso LibSQL here?

A: Drizzle is used to define schemas, migrations, and type-safe queries against Turso LibSQL; migrations live under drizzle/migrations and are executed via drizzle-kit.

Q: Can I adapt this for multiple environments?

A: Yes. Use environment variables for DB_URL, SESSION_SECRET, and TURSO_API_KEY; ensure migrations run in CI and production with a clean schema per environment.

Q: What is the recommended testing approach?

A: Use Vitest for unit/integration tests, and add a minimal end-to-end test to verify login and protected route access; run migrations in CI.