CLAUDE.md Template: Nuxt 4 + Cloudflare D1 + Better-Auth + Drizzle Starter Hooks

Overview

CLAUDE.md template for a Nuxt 4 stack that uses Cloudflare D1 as the database, Better-Auth for authentication, and Drizzle ORM for data access. This CLAUDE.md template page is a copyable Claude Code instruction block you can paste into CLAUDE.md. It provides architecture guidelines, file structure, and specific rules for secure, production-ready code.

Direct answer: This CLAUDE.md Template generates a Nuxt 4 app scaffold with Cloudflare D1, Better-Auth, and Drizzle ORM Starter Hooks, with a focus on clean separation of concerns and starter hooks.

When to Use This CLAUDE.md Template

• When starting a new Nuxt 4 project that runs on Cloudflare workers with D1 as the database.
• When you need coherent authentication flows via Better-Auth across server and client code.
• When you want a Drizzle ORM data access layer mapped to Cloudflare D1 tables with migrations.
• When you require starter hooks for user sessions, roles, and API guards.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude, a code generator responsible for producing a complete Nuxt 4 starter that uses Cloudflare D1, Better-Auth, and Drizzle ORM Starter Hooks. Outputs must be actionable Claude Code blocks that developers can paste into CLAUDE.md.

Architecture rules:
- Reactivity and Vue 3 composition API patterns within Nuxt 4, with a clear separation between UI, domain, and persistence layers.
- Use Cloudflare D1 as the database, accessed through Drizzle ORM.
- Centralize authentication with Better-Auth; enforce server-client boundary rules.
- Starter hooks provided for auth flows, user sessions, and role-based access.

File structure rules:
- Create a clean Nuxt 4 app layout with app/; place code in modules/ and libs/ when appropriate.
- Place Drizzle setup under drizzle/; migration and schema files under drizzle/migrations/.
- Keep environment-specific config in .env or runtimeConfig.
- Do not scatter config across unrelated folders.

Authentication rules:
- Use Better-Auth for session handling and access control.
- Do not expose private keys on the client; store secrets in environment variables and access via runtimeConfig.

Database rules:
- Use Cloudflare D1 properly; define tables that map to Drizzle models.
- Do not use unsupported Cloudflare features; ensure data safety with prepared statements.

Validation rules:
- Validate inputs with Zod schemas; propagate errors clearly; return structured error objects.

Security rules:
- Protect API routes with session validation and RBAC checks.
- Do not log secrets; sanitize error messages in production.

Testing rules:
- Unit tests for composables and utilities; integration tests for auth flows; end-to-end tests for critical user journeys.

Deployment rules:
- Build and deploy as a Nuxt 4 app on Cloudflare Workers or CI with proper env vars.
- Ensure migrations run in deployment hooks.

Things Claude must not do:
- Do not generate code that bypasses authentication.
- Do not use deprecated APIs in Nuxt 4 or Better-Auth.
- Do not hardcode production secrets in code or commits.

Recommended Project Structure

nuxt-cloudflare-d1-better-auth-drizzle-starter-hooks/
├─ nuxt-app/
│  ├─ app/
│  │  ├─ components/
│  │  ├─ layouts/
│  │  ├─ pages/
│  │  ├─ plugins/
│  │  └─ middleware/
│  ├─ nuxt.config.ts
│  ├─ package.json
│  └─ tsconfig.json
├─ drizzle/
│  ├─ drizzle.config.ts
│  ├─ migrations/
│  │  ├─ 20210501_initial.ts
│  │  └─ 20210501_add_users.ts
│  └─ schema.ts
├─ auth/
│  ├─ strategies/
│  │  └─ better-auth.ts
│  └─ middleware/
├─ hooks/
│  ├─ useUser.ts
│  └─ useAuthGuard.ts
└─ .env

Core Engineering Principles

• Explicit contracts between server and client via runtimeConfig and server routes.
• Type-safe data access with Drizzle ORM and Zod validation.
• Idempotent migrations and deterministic seeds for Cloudflare D1.
• Clear separation of concerns: UI, domain, and persistence layers.
• Secure defaults: least privilege, RBAC, and secret handling via environment variables.

Code Construction Rules

• Use TypeScript throughout the Nuxt 4 app.
• Define Drizzle models with a single source of truth and generate types from schema.
• Always validate inputs on the server and surface structured errors to clients.
• Use Better-Auth middleware for route protection; prefer server routes for sensitive logic.
• Keep API handlers small and focused; export small composables for reuse.

Security and Production Rules

• Never expose secrets in client-side code; use environment variables and runtimeConfig.
• Enable CSRF protection for state-changing API endpoints when needed.
• Encrypt sensitive data at rest where appropriate and audit access to secrets.
• Monitor error handling to avoid leaking stack traces in production.

Testing Checklist

• Unit tests for composables and utilities (Vitest).
• Integration tests for auth flows and drizzle queries.
• End-to-end tests for the main user journeys; run in CI before deployment.
• Run migrations in a safe environment before production deployments.

Common Mistakes to Avoid

• Skipping server-side validation leading to data inconsistencies.
• Allowing client-side secrets leakage or improper RBACs.
• Ignoring migration idempotency across environments.
• Hardcoding values that should come from environment configuration.

FAQ

• What does this CLAUDE.md Template cover? It provides a copyable Claude Code block for Nuxt 4 with Cloudflare D1, Better-Auth, and Drizzle Starter Hooks.
• Which stack is targeted? Nuxt 4 + Cloudflare D1 + Better-Auth + Drizzle ORM Starter Hooks.
• Can I paste the CLAUDE.md block directly? Yes. It starts with '# CLAUDE.md' and contains actionable instructions.
• What should I customize first? Environment, Cloudflare and Drizzle schemas, and auth hook configurations.
• Is this production-ready? Yes if you implement the security, testing, and deployment guidelines in the template.
• Where can I find related templates? See the CLAUDE.md Templates index.