CLAUDE.md Template: Next.js 16 + Cloudflare D1 (Edge SQLite) + Better-Auth + Drizzle ORM Setup

Overview

A CLAUDE.md template for a modern Next.js 16 app using Cloudflare D1 as Edge SQLite, Better-Auth for authentication, and Drizzle ORM for type-safe data access. This page provides a copyable CLAUDE.md block you can paste into your repository to bootstrap architecture, rules, and checks for this stack.

Direct answer: This template codifies the project role, architectural rules, and deployment constraints for this stack, enabling reproducible Claude Code templates for Next.js 16 with Cloudflare D1 and Drizzle ORM.

When to Use This CLAUDE.md Template

• You are building an edge-first Next.js 16 app that stores data on Cloudflare D1 (Edge SQLite).
• You want consistent authentication using Better-Auth with serverless routes and cookies.
• You prefer Drizzle ORM for type-safe data access with Cloudflare D1.
• You need a reproducible project scaffold with clear security and deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, a copyable CLAUDE.md template provider for a Next.js 16 + Cloudflare D1 + Better-Auth + Drizzle ORM stack. Your output must be a single, paste-ready CLAUDE.md block that codifies architecture, file structure, auth, database, validation, security, testing, and deployment rules.

Architecture rules:
- Base on Next.js 16 App Router with server components where appropriate.
- Use Cloudflare D1 as Edge SQLite backing store for development and production.
- Map data access through Drizzle ORM with a single source of truth for models.
- Integrate Better-Auth for authentication flows (signup, login, refresh, logout).
- Use TypeScript end-to-end; avoid JS-only hacks in critical paths.
- Isolate edge logic from any browser-only code; avoid Node-only libs on the client.

File structure rules:
- Root: project, with app/, lib/, drizzle/, db/ folders.
- app/ routes: pages exposed to the user live here; /app/api for server endpoints.
- drizzle/ contains migrations/ and schema.ts
- lib/ contains drizzle.ts and shared utilities
- db/ contains drizzle.config.ts and config for D1
- All code should be modular, with clearly defined exports
- Do not place ORM logic in client components

Authentication rules:
- Use Better-Auth for all auth flows; never expose credentials to the client.
- Store sessions in httpOnly, Secure cookies; set SameSite=Lax or Strict as appropriate.
- Use short-lived access tokens and rotate refresh tokens on every use.
- Do not store plaintext passwords; hash with strong algorithms.
- Validate CSRF tokens for state-changing requests.
- Implement sign-up verification and account recovery flows

Database rules:
- Cloudflare D1 as Edge SQLite; connect via Drizzle ORM.
- Use drizzle/schema.ts for models and drizzle.config.ts for connection.
- Use migrations directory to track schema changes
- Use parameterized queries via Drizzle; avoid raw string interpolation
- Back up migrations and ensure idempotent migrations

Validation rules:
- Validate user input with Zod at API/router boundaries.
- Enforce strict schemas for all inputs and outputs.
- Validate DB interactions with type-safe Drizzle models.

Security rules:
- Never log secrets; use environment variables for all sensitive data.
- Enforce TLS in all environments; set security headers (CSP, HSTS, etc.).
- Use role-based access control for protected routes.
- Do not expose internal implementation details in responses.

Testing rules:
- Unit tests for small helpers and validators
- Integration tests for DB interactions and auth flows
- End-to-end tests for login, signup, and protected routes
- CI must run tests on pushes and PRs

Deployment rules:
- Deploy to Cloudflare Pages/Workers with App Router integration.
- Set D1 database path and credentials in environment settings.
- Run migrations during deployment or on first boot.
- Ensure caching and edge routing rules align with your SLAs

Things Claude must not do:
- Do not introduce Prisma, Mongoose, or other ORMs not part of this stack.
- Do not propose insecure patterns (eg, storing secrets on the client).
- Do not bypass Better-Auth flows or skip token rotation.
- Do not hardcode secrets or credentials in code.
- Do not mix Edge and Node-only runtimes inappropriately.

Recommended Project Structure

Stack-specific directory tree for Next.js 16 + Cloudflare D1 + Better-Auth + Drizzle ORM:

ProjectRoot/
├─ app/
│  ├─ layout.tsx
│  ├─ page.tsx
│  ├─ components/
│  └─ api/
│     └─ auth/
├─ drizzle/
│  ├─ migrations/
│  │  └─ 001-initial.ts
│  └─ schema.ts
├─ lib/
│  └─ drizzle.ts
├─ db/
│  └─ drizzle.config.ts
└─ README.md

Core Engineering Principles

• Type-safe by default: strict TS types and zod schemas everywhere.
• Edge-first architecture: run critical paths on the Cloudflare Edge when possible.
• Single source of truth: define models in Drizzle and reuse them across API routes.
• Explicit dependencies: avoid dynamic imports that hurt tree-shaking and cold starts.
• Security by design: principle of least privilege and strong auth flows.

Code Construction Rules

• Do not use Node-only modules on the client side; keep client bundles clean.
• Do not bypass Drizzle migrations; run migrations in CI or deployment.
• Do not write raw SQL strings for queries; use Drizzle query builders and parameterized queries.
• Do not store secrets in source code; use environment variables and Cloudflare Secrets.
• Do not coupling auth logic with UI state; keep auth state in server session only.

Security and Production Rules

• Use httpOnly cookies for sessions; set Secure and SameSite appropriately.
• Enforce CSRF protection for all state-changing requests.
• Set Content-Security-Policy to limit inline scripts and external resources.
• Rotate tokens and implement session revocation for compromised accounts.
• Remediate vulnerabilities promptly; keep dependencies and runtime up to date.

Testing Checklist

• Unit tests for validators and utilities
• Integration tests for DB access through Drizzle ORM
• Integration tests for Better-Auth flows (signup, login, refresh, logout)
• End-to-end tests for protected routes and UI flows
• CI runs linting, type checks, and tests on PRs

Common Mistakes to Avoid

• Assuming Node-only behavior on the edge; do not run Node-only code in edge runtimes.
• Omitting migrations or relying on ad-hoc schema changes.
• Storing secrets in client-visible code or UI state.
• Mixing ORM contexts between server and client code.

FAQ

• What is CLAUDE.md Template? A copyable, stack-specific blueprint that encodes rules and structure for this exact stack.
• Which stack is supported? Next.js 16 + Cloudflare D1 (Edge SQLite) + Better-Auth + Drizzle ORM.
• Can I adapt this to other data stores? Yes, but you should adjust the ORM and migrations accordingly and update the CLAUDE.md block accordingly.
• Where are credentials stored? In environment variables or secret managers; not in code or the CLAUDE.md block.
• How do I run migrations? Run the drizzle migrate script during deployment or via a CI job; ensure D1 is accessible.