Nuxt 4 + PlanetScale MySQL + Auth0 + Prisma ORM - CLAUDE.md Template

Overview

CLAUDE.md template for Nuxt 4 + PlanetScale MySQL + Auth0 + Prisma ORM provides a ready-to-paste blueprint that codifies architecture decisions, file layout, and security practices for this stack. This page is a copyable CLAUDE.md template page you can drop into Claude Code to accelerate project setup and onboarding.

When to Use This CLAUDE.md Template

• You are starting a Nuxt 4 project that uses Prisma ORM to talk to a MySQL-compatible database on PlanetScale.
• You want Auth0-based authentication with proper session handling and secure token storage.
• You need a disciplined, copy-pasteable CLAUDE.md template for rapid team alignment and documentation generation.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude, a code automation assistant that outputs a concise, install-ready CLAUDE.md template for a Nuxt 4 project using PlanetScale MySQL, Auth0, and Prisma ORM. Provide actionable steps and enforce stack constraints.

Architecture rules:
- Target stack: Nuxt 4 (App Router) + Prisma ORM connected to PlanetScale MySQL.
- Use Auth0 for authentication with SPA SDK on the client and a server route for sessions.
- Prisma Client must be generated and used in server/loaders and composables, not raw queries.
- Environment-based configuration only (no hard-coded credentials).
- Strict TypeScript usage with strict mode enabled.
- Avoid coupling to non-MySQL databases; PlanetScale is the MySQL provider.
- All database migrations must be tracked by Prisma Migrate.

File structure rules:
- nuxt.config.ts at project root
- app/ (Nuxt 4 App Router)
- components/
- composables/
- plugins/auth.ts (Auth0 integration)
- prisma/schema.prisma
- server/api/auth/ (Auth related server routes)
- .env and .env.example
- migrations/ (Prisma migrations)
- README.md with setup instructions

Authentication rules:
- Use Auth0 domain, clientId, and audience via environment variables.
- Implement login/logout on the client and a session verification route on the server.
- Store session state in secure, HttpOnly cookies when possible; do not rely on localStorage for tokens.
- Validate and refresh tokens server-side; never trust client-side data alone.

Database rules:
- PlanetScale MySQL is the datasource provider.
- DATABASE_URL must be set in .env; include shadowDatabaseUrl for migrations if needed.
- Prisma schema should define models aligned with your app (e.g., User, Post) and relation mappings.
- Use Prisma migrations to evolve schema; never edit the database directly in production.
- Do not embed raw SQL strings in app code; use Prisma where possible.

Validation rules:
- Use Zod for runtime validation in server routes and in forms.
- Validate request payloads before any business logic executes.
- Return well-formed error messages and do not leak internal schema details.

Security rules:
- Enable CSRF protection for mutating endpoints.
- Use secure, HttpOnly cookies with SameSite strict where applicable.
- Validate JWT scopes/roles from Auth0 before accessing protected resources.
- Rotate and manage secrets via environment configuration; do not commit them.

Testing rules:
- Unit tests with Vitest for utilities and middlewares.
- Integration tests with Playwright or Cypress for key user flows.
- Ensure Prisma client is mocked in unit tests; do not rely on a live database in unit tests.
- CI should run lint, type-check, tests, and a basic build.

Deployment rules:
- Deploy to a hosting platform that supports Nuxt 4 (e.g., Vercel). Ensure serverless functions can handle API routes.
- Set all environment variables in the hosting platform.
- Run Prisma generate in build/runtime as needed; apply migrations during deploy with care.

Things Claude must not do:
- Do not bypass Auth0 authentication or expose tokens in client code.
- Do not hardcode credentials or database URLs.
- Do not perform production database migrations without a review step.
- Do not propose or generate non-MySQL (e.g., PostgreSQL) specific configurations for PlanetScale.
- Do not generate boilerplate code that ignores Nuxt 4 App Router conventions.

Recommended Project Structure

nuxt-app/
  nuxt.config.ts
  app/
    root-layout.vue
    pages/
      index.vue
  components/
  composables/
  plugins/
  prisma/
    schema.prisma
  server/
    api/
      auth/
  migrations/
  .env
  .env.example
  README.md
  package.json

Core Engineering Principles

• Strong typing and explicit interfaces across server and client sides.
• Environment-driven configuration with no hard-coded secrets.
• Principled data access via Prisma ORM; rely on Prisma for migrations and client generation.
• Secure authentication with Auth0; token validation on server boundaries.
• Clear separation of concerns between UI, API, and data access layers.

Code Construction Rules

• Connect Prisma to PlanetScale MySQL via DATABASE_URL in .env; ensure correct provider in schema.prisma.
• Generate Prisma client and keep it as a dependency in server code only.
• Use Nuxt 4 App Router conventions; place server routes under server/api.
• Use Zod for request validation; return precise error messages.
• Abstract Auth0 logic into composables/plugins; avoid embedding config in components.
• Do not hardcode secrets; keep them in environment variables.

Security and Production Rules

• CSRF protection enabled for mutating endpoints; use SameSite cookies.
• Validate tokens against Auth0; enforce role/permission checks server-side.
• Limit CORS to your frontend domain; disable verbose error output in production.
• Rotate credentials and review access rules regularly; never publish keys.

Testing Checklist

• Unit tests for utilities and validators (Vitest).
• Integration tests for API endpoints (Prisma interactions) with a test database or mocked clients.
• E2E tests for login, protected routes, and data flows (Playwright or Cypress).
• CI runs lint, tests, type checks, and a smoke build.

Common Mistakes to Avoid

• Relying on client-side only authentication; validate on server side as well.
• Hardcoding credentials or database URLs in code or CLIs.
• Using non-secure cookies or leaking secrets via error messages.
• Ignoring Prisma migrations in production; always migrate with a review step.

FAQ