Nuxt 4 + CockroachDB + Custom Cookie Session Auth + TypeORM Boilerplate — CLAUDE.md Template

Overview

The CLAUDE.md template is designed for developers building a Nuxt 4 application that uses CockroachDB via TypeORM and implements a custom cookie-based session authentication flow. This page is a copyable CLAUDE.md Template page that guides Claude Code to bootstrap, secure, and deploy a production-ready stack with clear constraints and checks.

• Direct answer: This template bootstraps Nuxt 4, configures CockroachDB with TypeORM, and establishes a cookie-based session auth flow, with production-ready security and testing rules.
• Stack focus: Nuxt 4, CockroachDB, TypeORM, custom cookie-session authentication, and server-rendered capabilities.

When to Use This CLAUDE.md Template

• You are starting a Nuxt 4 project needing a relational DB with distributed transactions (CockroachDB).
• You require an ORM layer (TypeORM) for data access and migrations.
• You need a custom cookie-based session authentication mechanism suitable for SSR/CSR flows.
• You want a single copyable CLAUDE.md Template that Claude Code can follow for consistent results.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior Nuxt 4 full-stack engineer responsible for bootstrapping a Nuxt 4 app with CockroachDB using TypeORM, and implementing custom cookie-based session authentication. Provide Claude Code instructions that enable fast, correct setup, consistent validation, and secure deployment.

Architecture rules:
- Client/server boundary: Nuxt 4 app with Nitro server handles API routes; ORM operates on the server side.
- Database: CockroachDB as the primary relational store; use TypeORM to model entities and migrations.
- Session model: cookie-based, server-validated session; store session data in CockroachDB with a signed session_id cookie.
- Config: environment-driven; avoid hard-coded secrets in code. Use a dedicated config module for all credentials and URLs.
- Deployment: all services containerized; separate DB credentials from app code.

File structure rules:
- orm/entities/ for TypeORM entities
- orm/migrations/ for TypeORM migrations
- orm/datasource.ts to configure the TypeORM DataSource
- server/ for API endpoints and session handling
- config/ CockroachDB config and environment management
- nuxt.config.ts at repository root
- pages/ app/views under app/pages (Nuxt 4 structure)

Authentication rules:
- Use an HttpOnly, Secure, SameSite=Strict cookie named session_id
- Server must validate session_id against a CockroachDB-backed sessions table
- Passwords stored as salted hashes (bcrypt) with per-user iterations
- CSRF protection for mutating endpoints when SSR interactions occur

Database rules:
- CockroachDB with proper connection pooling; use migrations for schema changes
- Use parameterized queries through TypeORM; never interpolate user input in raw queries
- Index frequently queried fields
- Avoid N+1 queries with eager loading and proper relations

Validation rules:
- Validate input shapes with explicit DTOs and type guards
- Validate session presence before protected endpoints
- Validate data types and constraints before writes

Security rules:
- Do not log sensitive data; mask secrets in logs
- Do not bypass TLS in production; force HTTPS
- Do not store plaintext passwords
- Do not expose DB credentials in client code

Testing rules:
- Unit tests for ORM entities and DTO validators
- Integration tests for session flows and DB access
- End-to-end tests for login/logout flows
- Linting and type checks as part of CI

Deployment rules:
- Use Docker/Kubernetes; ensure DB migrations run on startup
- Seed data during CI where appropriate
- Environment-specific configs via env vars only

Things Claude must not do:
- Do not bypass authentication checks on protected routes
- Do not skip migrations before startup
- Do not use string concatenation for SQL; always use parameters
- Do not enable insecure cookies in production
- Do not ship secrets in the image

Recommended Project Structure

nuxt-app/
  nuxt.config.ts
  package.json
  tsconfig.json
  app/
    components/
    layouts/
    pages/
    plugins/
  orm/
    entities/
    migrations/
    datasource.ts
  server/
    api/
  config/
    cockroachdb.ts

Core Engineering Principles

• Clear separation of concerns between data, API, and UI layers.
• Idempotent migrations and strict schema evolution.
• Secure by default: minimal surface area, safe defaults, and TLS required in prod.
• Type-safe data access with TypeORM and DTO-driven validation.
• Observability: structured logs, metrics, and traces for critical paths.
• Environment parity: local mirrors production as much as possible.

Code Construction Rules

• Initialize TypeORM DataSource once at server startup in orm/datasource.ts and reuse across requests.
• Define clear entities for all schemas and rely on migrations for changes.
• Use parameterized queries via TypeORM to prevent SQL injection.
• Implement session handling in server code, persisting sessions in CockroachDB.
• Hash passwords with bcrypt and store salted hashes; never store plaintext passwords.
• Keep config in environment variables; never embed secrets in code.
• Follow a consistent file naming convention; group ORM code in orm/.
• Use strict type guards for inputs; reject invalid data early.
• Do not import browser-only modules in server code; isolate runtime environments.

Security and Production Rules

• Cookies: HttpOnly, Secure (in production), SameSite=Strict, with a short session lifetime.
• Always run with TLS in production; enforce https and HSTS where possible.
• Rotate session IDs after login and on sensitive actions.
• Enable database-level access controls and least-privilege DB users.
• Protect endpoints with CSRF tokens for state-changing operations.

Testing Checklist

• Unit tests for DTOs, validators, and ORM entities.
• Integration tests for DB interactions and session flows.
• End-to-end tests for login/logout and protected routes.
• CI checks for type safety, lint, and migrations running on push.
• Production-like load tests focusing on connection pooling to CockroachDB.

Common Mistakes to Avoid

• Hard-coding credentials or secrets in code or images.
• Skipping migrations or enabling automatic destructive migrations.
• Storing session data in memory without a shared store for multi-instance deployments.
• Using insecure cookies in production or disabling TLS.
• Neglecting input validation leading to common attack surfaces.

FAQ