CLAUDE.md Template: Nuxt 4 + PostgreSQL + Nuxt Auth Utils + Prisma ORM Blueprint

Overview

Direct answer: This CLAUDE.md template provides a repeatable blueprint for Nuxt 4 + PostgreSQL + Nuxt Auth Utils + Prisma ORM, with a copy-paste CLAUDE.md block that you can drop into Claude Code to generate a production-ready app skeleton.

When to Use This CLAUDE.md Template

• Starting a new Nuxt 4 project that targets PostgreSQL as the primary database.
• Integrating Prisma ORM for type-safe database access in Nuxt 4.
• Setting up authentication using Nuxt Auth Utils with server-side sessions or JWTs.
• Creating a project that requires a clean separation of server and client logic with Nuxt 4 Nitro.
• Building APIs that are protected and scalable with Prisma models.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a full-stack architect that designs a Nuxt 4 + PostgreSQL + Nuxt Auth Utils + Prisma ORM stack with Claude Code.

Architecture rules:
- Use Nuxt 4 (with Nitro) for server and client separation.
- PostgreSQL as the database, accessed via Prisma ORM.
- Authentication via Nuxt Auth Utils using either local cookies or JWTs depending on session strategy.
- All API routes protected by middleware to enforce roles and permissions.
- Environment-specific configurations must be centralized in .env files and loaded by runtime config.

File structure rules:
- Keep a clean separation between app code (nuxt-app) and database/schema (prisma).
- Use conventional file names with clear module boundaries.
- All API endpoints live under server/api.

Authentication rules:
- Passwords must be hashed using bcrypt.
- Sessions stored securely with httpOnly cookies; refresh tokens rotated.
- Access tokens expire within a defined short window (e.g., 15 minutes); refresh tokens extend session.

Database rules:
- Prisma schema defines models for User, Role, Post, and Any necessary domain models.
- Use relational relations to enforce foreign keys.
- Use migrations to evolve schema; seed data in a dedicated seed script.

Validation rules:
- Validate request payloads with zod-like schemas (or native schema validation) and fail fast.
- Return structured errors with field-level messages.

Security rules:
- Do not expose database credentials in client code.
- Enable CSRF protection for state-changing requests.
- Enable CORS with a tight policy for the API domain.
- Do not bypass authentication checks on private routes.

Testing rules:
- Unit tests for composables and utilities.
- Integration tests for Prisma queries and Nuxt server routes.
- End-to-end tests using a dedicated test database.

Deployment rules:
- Environment variables loaded from a secure vault.
- Build cache invalidation on schema changes.
- Use containerized deployments with health checks.

Things Claude must not do:
- Do not generate insecure secret keys or hard-coded credentials.
- Do not assume database exists without migrations.
- Do not skip authentication or authorization checks on protected routes.
- Do not rely on client-side only validation for security.

Recommended Project Structure

nuxt-app/
├── components/
├── composables/
├── layouts/
├── pages/
├── plugins/
├── server/
│   └── api/
├── middleware/
├── prisma/
│   └── schema.prisma
├── .env
├── nuxt.config.ts
├── package.json
└── tsconfig.json

Core Engineering Principles

• Explicit contracts between client and server via typed APIs and Prisma models.
• Single source of truth for configuration (runtimeConfig, env vars).
• Security-first by default: authentication, authorization, and input validation.
• Idempotent deployments with clear rollback paths.
• Observable code: clear logging, metrics, and error handling.

Code Construction Rules

• Use Nuxt 4 with Nitro for server routes under server/api.
• Access Prisma via a typed client wrapper; keep database logic in a dedicated service layer.
• Authenticate requests using Nuxt Auth Utils; protect pages and API routes with middleware.
• All models defined in prisma/schema.prisma with migrations for changes.
• Environment variables must be read at startup and not embedded in code.
• Use TypeScript consistently across app codebase.
• Do not hard-code secrets; use environment variables and a secret management service in production.

Security and Production Rules

• Enable server-side rendering security best practices; set csp headers and strict transport security.
• Store DB credentials securely; rotate keys regularly.
• CSRF protection for state-changing requests; use sameSite cookies.
• Limit API exposure with precise CORS rules and rate limiting where needed.
• Audit logs for authentication events and data access.

Testing Checklist

• Unit tests for composables and helpers.
• Integration tests for Prisma queries and Nuxt server routes.
• End-to-end tests covering login flow and protected routes with Nuxt Auth Utils.
• CI checks for type safety and linting; ensure migrations run on test DB.

Common Mistakes to Avoid

• Mixing client and server secrets; exposing credentials in client code.
• Skipping Prisma migrations or seeding in development.
• Not validating inputs, leading to insecure operations.
• Ignoring CSRF and improper cookie handling for auth tokens.

FAQ

• What is this CLAUDE.md Template for? It provides a ready-to-copy CLAUDE.md block to scaffold a Nuxt 4 + PostgreSQL + Nuxt Auth Utils + Prisma ORM stack.
• Can I customize the Prisma models easily? Yes; the template provides a clean Prisma schema in prisma/schema.prisma and a seed script.
• How is authentication secured? Nuxt Auth Utils with httpOnly cookies or JWTs, token rotation, and CSRF protection.
• Where do I place server routes? Under server/api with Nitro; protected by middleware.
• How do I test this stack? Unit tests for utilities, integration tests for Prisma, and E2E tests for login and protected routes.