Remix Framework + Cloudflare KV & D1 + Better-Auth + Drizzle ORM Edge Build — CLAUDE.md Template (CLAUDE.md template)

Overview

Direct answer: This CLAUDE.md template provides a copyable blueprint to build an edge-first Remix app on Cloudflare KV and D1, using Better-Auth and Drizzle ORM, ready for Claude Code execution.

The stack covered: Remix Framework, Cloudflare KV for caching, Cloudflare D1 as the database, Better-Auth for authentication, and Drizzle ORM for data access, all optimized for edge builds.

When to Use This CLAUDE.md Template

• Starting a new edge-first Remix project on Cloudflare
• Prototype authentication flows using Better-Auth
• Define DB models with Drizzle ORM on Cloudflare D1
• Design edge-friendly data access patterns and caching with KV
• Provide a secure, testable architecture for Claude Code templates
• Deploy to Cloudflare Workers with an edge-friendly deployment

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are a Claude Code assistant that outputs a Remix + Cloudflare KV/D1 + Better-Auth + Drizzle ORM Edge Build blueprint. The aim is to enable a developer to paste this into CLAUDE.md and immediately start implementing an edge-first Remix app on Cloudflare.
Architecture rules:
- Edge-first: route and data access run at the Cloudflare edge when possible.
- Use Cloudflare D1 as the canonical relational store; use Drizzle ORM for type-safe queries and migrations.
- Cache and session data live in Cloudflare KV with proper TTLs.
- Avoid cross-region calls; favor edge caches and batched writes.
File structure rules:
- Respect Remix conventions: app/, routes/, entry.client.tsx, entry.server.tsx, root.tsx.
- Place DB models under drizzle/, migrations under drizzle/migrations/.
- Place Cloudflare integrations under cloudflare/kv/ and cloudflare/d1/.
- Do not place unrelated tech stacks in the repo.
Authentication rules:
- Prefer Better-Auth with HTTP-only cookies; avoid localStorage for tokens.
- Protect sensitive endpoints with middleware that validates tokens and scopes.
- Do not expose user tokens to the client.
Database rules:
- Use Drizzle ORM to define tables and relations in db/schema.ts.
- Migrate with drizzle generate and drizzle db push in CI.
- Use D1 connection string from environment; never hard-code credentials.
Validation rules:
- Validate inputs server-side using zod in loaders/actions.
- Return structured errors with status codes and messages for the client.
Security rules:
- Enforce Content-Security-Policy and Strict-Transport-Security where applicable.
- Never log secrets; redact sensitive fields in logs.
- Ensure cookies are HttpOnly and Secure in production.
Testing rules:
- Unit tests for data access (Drizzle queries, migrations).
- Integration tests for auth flows and protected endpoints.
- Deployment checks that edge build passes and KV/D1 bindings exist.
Deployment rules:
- Use wrangler for Cloudflare deployment; configure KV namespaces and D1 bindings.
- Run edge builds in CI and publish with wrangler publish.
- Include rollback paths and monitoring hooks.
Things Claude must not do:
- Do not bypass CI checks or hard-code secrets.
- Do not perform unauthenticated writes to D1 or KV.
- Do not call external services without explicit consent in the template.
- Do not mutate Cloudflare account configuration outside defined bindings.

Recommended Project Structure

project-root/
├─ package.json
├─ remix.config.js
├─ wrangler.toml
├─ .env (DO NOT commit in production)
├─ app/
│  ├─ entry.client.tsx
│  ├─ entry.server.tsx
│  ├─ root.tsx
│  └─ routes/
│     ├─ index.tsx
│     ├─ login.tsx
│     └─ api/
│        └─ auth.ts
├─ drizzle/
│  ├─ client.ts
│  ├─ schema.ts
│  └─ migrations/
│     └─ 001-create-users.ts
├─ db/
│  ├─ migrations/
│  │  └─ 001-create-tables.ts
│  └─ schema.ts
├─ cloudflare/
│  ├─ kv/
│  │  └─ index.ts
│  └─ d1/
│     └─ migrations/
│        └─ 001-create-tables.sql

Core Engineering Principles

• Edge-first, low-latency design with Remix on Cloudflare Workers.
• Strong type safety across the stack using Drizzle ORM and TypeScript.
• Security-by-default: HTTP-only cookies, strict validation, and minimal surface area.
• Modular architecture: separate concerns for DB, auth, and API layers.
• Observability: clear logging, error boundaries, and predictable behavior in edge environments.

Code Construction Rules

• Use Remix loaders/actions to fetch and mutate Cloudflare D1 data via Drizzle ORM.
• Keep server code isolated from client bundles; avoid leaking secrets to the browser.
• Define DB models in drizzle/schema.ts and migrate via drizzle migrations.
• Store session state in Cloudflare KV with proper TTL and rotation policies.
• Validate all inputs server-side with a strict schema (e.g., zod) and return helpful errors.
• Use Better-Auth utilities for token issuance, verification, and scope checks.
• Prefer edge-compatible APIs and avoid long-running server-side tasks in loaders.
• Do not rely on browser storage for auth tokens; always use HTTP-only cookies.

Security and Production Rules

• Environment secrets must come from process.env and never be checked into source.
• Cookies must be HttpOnly, Secure (in production), and SameSite=Lax or Strict.
• Enable CSP, COOP/COEP as appropriate, and use HTTPS in all environments.
• Implement rate limiting and CSRF protection for state-changing endpoints.
• Audit logs must redact sensitive user data; never log tokens or credentials.

Testing Checklist

• Unit tests for Drizzle models and queries.
• Integration tests for auth flows and protected endpoints.
• End-to-end tests for signup, login, protected content, and logout.
• CI checks to ensure edge build, D1, and KV bindings exist before deployment.

Common Mistakes to Avoid

• Assuming browser-side code can securely perform DB writes.
• Storing secrets in source or client code.
• Overusing global state that breaks edge caching semantics.
• Inadequate tests for edge routing and data access patterns.
• Skipping migrations and relying on ad-hoc schema changes.

FAQ

What is this CLAUDE.md template for Remix + Cloudflare KV/D1?

A copyable CLAUDE.md template that guides building an edge-first Remix app with Cloudflare KV for caching, Cloudflare D1 as the database, Better-Auth for authentication, and Drizzle ORM for data access.

How do I run this locally?

Clone the repository, install dependencies, run the Remix dev server, and use wrangler dev for Cloudflare Workers testing. Paste the CLAUDE.md code into Claude Code to follow the blueprint.

How do I deploy to Cloudflare Edge?

Configure wrangler.toml with your account, set KV and D1 bindings, and run wrangler publish to deploy to the edge.

Why use Drizzle ORM with Cloudflare D1?

Drizzle provides a type-safe SQL experience and migrations on Cloudflare D1, improving DX and reliability.

Can I customize authentication with Better-Auth?

Yes. The template demonstrates a modular Better-Auth setup with token-based access and HTTP-only cookies; adjust providers and scopes as needed.