Nuxt 4 + Supabase DB + Supabase Auth + Drizzle ORM Full-Stack Stack — CLAUDE.md Template

Overview

The CLAUDE.md template provides a repeatable blueprint for a Nuxt 4 + Supabase DB + Supabase Auth + Drizzle ORM full-stack application. It delivers practical Claude Code instructions that you can paste directly into CLAUDE.md to bootstrap a production-ready project focused on secure authentication, Postgres-backed data, and strongly-typed data access via Drizzle ORM.

Direct answer: This template yields a working Nuxt 4 app with Supabase authentication, a Postgres database, and Drizzle ORM for data access, all wired through Claude Code-friendly instructions.

When to Use This CLAUDE.md Template

• Starting a new Nuxt 4 project that requires user authentication with Supabase.
• Building a server-rendered app with SSR-friendly data access via Drizzle ORM.
• Prototyping a secure full-stack architecture with clearly defined boundaries between client, server, and database layers.
• Educating teams on a repeatable Nuxt 4 + Supabase + Drizzle pattern with production-grade guardrails.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Platform Engineer leading Nuxt 4 + Supabase + Drizzle ORM full-stack implementation.

Architecture rules:
- Use a clean separation of concerns: client (Nuxt app), server (Nuxt server routes), and db (Drizzle ORM accessing Postgres).
- All DB access must go through Drizzle ORM; avoid raw SQL in app code.
- Use environment-driven configuration; never hardcode secrets in code.
- Implement Row Level Security (RLS) in Supabase DB where appropriate.
- Prefer server-side rendering with data fetched via server routes for SEO and security.

File structure rules:
- Maintain a src/app structure compatible with Nuxt 4 conventions.
- Place DB models and migrations under db/drizzle and db/migrations.
- Store API helpers under server/api; client utilities under src/composables.
- Use a single config module to expose env vars or feature flags.

Authentication rules:
- Use Supabase Auth with email/password and OAuth providers if needed.
- Do not store user secrets on the client; rely on server-validated sessions.
- Validate all authentication claims on the server before proceeding.

Database rules:
- PostgreSQL as the Supabase DB; enable RLS per table when exposing user-scoped data.
- Use Drizzle ORM models for all data operations.
- Run migrations via drizzle-kit and track schema changes.

Validation rules:
- Validate inputs on both client and server; server validation is authoritative.
- Use Zod schemas for runtime validation and TypeScript types for compile-time checks.

Security rules:
- Enforce CSP, HTTPS-only endpoints, and secure cookies.
- Never expose DB connection strings or service keys to the client.
- Apply rate limiting and proper auth checks on protected routes.

Testing rules:
- Unit tests for utilities and validators.
- Integration tests for server routes and DB interactions (mocked DB for unit tests).
- End-to-end tests covering login, data write, and data read flows.

Deployment rules:
- Set up environment-specific overrides; keep secrets in a safe secret store.
- Review migrations during deployment; ensure Travis/CI pipelines run tests before merging.
- Use evergreen deployment to ensure reproducible builds.

Things Claude must not do:
- Do not bypass server validation or perform client-only auth checks.
- Do not store credentials or secrets on the client.
- Do not use arbitrary SQL for data access; avoid string-concatenated queries.
- Do not ignore DB migrations or skip security hardening steps.

Recommended Project Structure

nuxt4-supabase-app/
├─ app/
├─ components/
├─ layouts/
├─ pages/
├─ composables/
├─ plugins/
├─ public/
├─ server/
│  └─ api/
├─ db/
│  ├─ drizzle/
│  │  ├─ index.ts
│  │  ├─ models/
│  │  └─ migrations/
│  └─ migrations/
└─ package.json

Core Engineering Principles

• Security by default: validate on the server, never trust client input.
• Strong typing across client and server with clear boundaries.
• Explicit data access via Drizzle ORM; avoid raw queries.
• Idempotent deployments and reproducible migrations.
• Observability: structured logging and error reporting.
• Accessible, SEO-friendly server-rendered pages when relevant.

Code Construction Rules

• Use Nuxt 4 with TypeScript; enable strict mode.
• Client code must import from composables; server routes handle DB access.
• Drizzle ORM models must reflect Supabase Postgres schema; keep migrations in db/migrations.
• Use Zod for input validation and propagate types to the client.
• Secret management via environment variables; never commit secrets.
• Follow a consistent naming convention for tables, models, and routes.

Security and Production Rules

• Enable Row Level Security on tables exposing user data; implement policies.
• Use secure cookies, CSRF protection, and HTTPS in all environments.
• Never bundle DB credentials in client bundles; proxy via server routes.
• Limit data exposure in API responses; implement least-privilege data access.
• Regularly review dependencies for known vulnerabilities.

Testing Checklist

• Unit tests for validators, helpers, and Drizzle model logic.
• Integration tests for server routes with a test Postgres database.
• Migration tests to ensure schema changes apply cleanly.
• End-to-end tests for login, data creation, and data retrieval flows.
• Security tests including auth, route guards, and data exposure checks.

Common Mistakes to Avoid

• Relying on client-side validation for security-sensitive checks.
• Skipping migrations or mutating schemas without version control.
• Using raw SQL queries with string concatenation leading to SQL injection risks.
• Ignoring Row Level Security or exposing user data unintentionally.
• Storing secrets in version control or frontend code.

FAQ