Nuxt 4 + Turso Database + Clerk Auth + Drizzle ORM Architecture — CLAUDE.md Template

Overview

A CLAUDE.md Template for Nuxt 4 + Turso Database + Clerk Auth + Drizzle ORM Architecture. It provides a copyable blueprint that you can paste into Claude Code to generate a complete, production-ready setup across frontend routing, authentication, data access, and deployment rules. This page is a copyable CLAUDE.md template page, tailored to the Nuxt 4 stack with Turso, Clerk, and Drizzle ORM.

When to Use This CLAUDE.md Template

• Starting a Nuxt 4 project with Turso as the database and Clerk for authentication
• Setting up Drizzle ORM for type-safe data access against Turso
• Enforcing architecture constraints from the outset to avoid drift
• Generating a reproducible project skeleton that Claude can apply to CI pipelines

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, producing a precise, copyable CLAUDE.md template for a Nuxt 4 + Turso + Clerk + Drizzle ORM architecture blueprint.

Architecture rules:
- Target stack: Nuxt 4 frontend, Turso as the database, Clerk for authentication, Drizzle ORM for data access.
- All code must be TypeScript where possible and fully typed.
- Do not bypass authentication checks on protected routes.

File structure rules:
- Maintain a clean, conventional Nuxt 4 project layout.
- Place database models and migrations under a dedicated server/lib or server/db directory.
- Centralize environment-specific config in .env and runtime config.

Authentication rules:
- Use Clerk for login, signup, and session management.
- Route guards must reject requests from unauthenticated users.
- Never expose user tokens to the client.

Database rules:
- Use Turso in a server-side context; never connect Turso from the client.
- Use Drizzle ORM models for all data access with well-typed queries.
- Migrate schemas using a migration folder; track migrations with timestamped files.

Validation rules:
- Validate all inputs on the server; never trust client data.
- Use zod schemas for request validation and error handling.

Security rules:
- Store secrets in environment variables; do not commit them.
- Use secure cookies, CSRF protection, and strict Content Security Policy (CSP).
- Enable network-level rate limiting on API endpoints.

Testing rules:
- Include unit tests for validations and data access layers.
- Include integration tests for auth flows and DB queries.
- Run tests in CI before deployment.

Deployment rules:
- Provide a deterministic build that runs on Vercel/Netlify or your preferred host.
- Environment variables must be defined in the hosting provider.
- Ensure migrations run during deployment.

Things Claude must not do:
- Do not bypass authentication or authorization checks.
- Do not produce SQL that concatenates user input directly.
- Do not assume client-side secrets or credentials.
- Do not include unused dependencies or frameworks.

Recommended Project Structure

nuxt-app/
├─ nuxt.config.ts
├─ package.json
├─ app/
│  ├─ components/
│  ├─ layouts/
│  └─ pages/
├─ server/
│  ├─ api/
│  ├─ db/
│  │  ├─ migrations/
│  │  └─ drizzle.ts
│  └─ middleware/
├─ lib/
│  └─ drizzle/

Core Engineering Principles

• Explicit architecture: Clear separation between frontend, backend, and data access.
• Type safety: End-to-end TypeScript usage with Drizzle ORM typings.
• Security by default: Auth, validation, and CSP enforced from the start.
• Repeatability: Deterministic structure and migrations for consistent deployments.
• Observability: Structured error handling and logging for faster debugging.

Code Construction Rules

• Always fetch data server-side when it touches the database; avoid client-side Turso calls.
• Define Drizzle models in a single source of truth and reuse across API routes.
• Validate inputs with zod before processing logic or DB calls.
• Prefer typed DTOs for API requests and responses.
• Keep environment variables out of source code; access via process.env or runtime config.

Security and Production Rules

• Authenticate with Clerk for protected routes; enforce authorization on data access layers.
• Store secrets in environment variables; rotate them periodically.
• Enable CSRF protection and secure cookies; set strict CSP.
• Protect API routes with rate limiting and proper error handling.

Testing Checklist

• Unit tests for request validators (zod) and Drizzle DB helpers.
• Integration tests for authentication flows with Clerk.
• End-to-end tests covering login, data fetch, and data mutation flows.
• CI must run tests and verify migrations before deployment.

Common Mistakes to Avoid

• Exposing server secrets to the client.
• Skipping server-side validation for API endpoints.
• Mixing ORM data access with raw SQL queries in business logic.
• Forgetting to run migrations in production deployments.

FAQ

What is this CLAUDE.md Template for?

A copyable blueprint for Nuxt 4 + Turso + Clerk + Drizzle ORM architecture, designed to be pasted into Claude Code.

Which stacks does it cover?

Nuxt 4 frontend, Turso database, Clerk authentication, and Drizzle ORM for DB access.

How do I integrate Clerk?

Use Clerk's SDK in Nuxt 4 server routes and middleware; protect pages and API endpoints with Clerk guards.

How do I configure Turso with Drizzle?

Define Drizzle models in server code and configure a Turso connection string in server runtime config; do not call from client.

What tests should I run?

Unit tests for validators, integration tests for auth and DB, and end-to-end tests for user flows.

Where should I deploy?

Any modern host that supports Nuxt 4 (Vercel, Netlify, or your cloud provider); ensure migrations run on deploy.