CLAUDE.md Template: Next.js + PostgreSQL — CLAUDE.md template for Next.js with PostgreSQL

Overview

CLAUDE.md template is a copyable Claude Code blueprint for building a production-ready Next.js + PostgreSQL app. It includes a ready-to-paste CLAUDE.md block, stack-specific project structure, and explicit engineering rules to keep architecture coherent across teams.

Direct answer: This CLAUDE.md template delivers a drop-in Claude Code payload for a Next.js + PostgreSQL stack, covering architecture, file layout, authentication, validation, security, testing, and deployment guidelines.

When to Use This CLAUDE.md Template

• Starting a new Next.js project that uses PostgreSQL as the data store.
• Establishing a standard architecture and rules for fast onboarding and consistency.
• Producing a copyable CLAUDE.md template for QA checks and reproducible results.
• Documenting stack-specific validation, security, and deployment guidelines in one place.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: Full-stack Engineer for a Next.js app with PostgreSQL backend.

Architecture Rules:
- Frontend: Next.js App Router (src/app), server components where appropriate; lean client components.
- Backend: PostgreSQL as the primary data store; access via a minimal data layer using the 'pg' library with a Pool.
- API Layer: Typed Next.js API routes or app router endpoints; define DTOs and enforce runtime validation.
- Secrets and configuration: Use environment variables; never embed secrets in code; use a dedicated secret manager in production.

File Structure Rules:
- src/
  - app/
    - page.tsx
    - /api/
      - users.ts
      - posts.ts
  - components/
    - Layout.tsx
    - Nav.tsx
  - lib/
    - db.ts
  - db/
    - migrations/
      - 001_init.sql
- .env.example at project root.

Authentication Rules:
- Use NextAuth.js with JWT sessions stored in HttpOnly cookies; protect sensitive routes with middleware.
- Only authenticated users can perform write operations; admin endpoints require role check.

Database Rules:
- PostgreSQL with a single primary database per environment; connection via Pool with max 10 connections; TLS enabled; migrations stored in db/migrations.
- Use parameterized queries to prevent SQL injection; avoid string concatenation.

Validation Rules:
- Validate all inputs server-side using Zod; validate response shapes; never leak unvalidated data to clients.

Security Rules:
- Implement Content-Security-Policy, Strict-Transport-Security; HttpOnly cookies; CSRF protection on state-changing requests.
- Do not log secrets; sanitize all error messages in production.

Testing Rules:
- Unit tests for utilities and validation schemas.
- Integration tests for API routes with a PostgreSQL test database.
- End-to-end tests for critical user flows.

Deployment Rules:
- Deploy to Vercel or a container-based host; configure env vars securely; enable TLS; set up database connection string via environment tooling.

Things Claude must not do:
- Do not perform client-side SQL queries or direct DB access from the browser.
- Do not bypass authentication or authorization checks.
- Do not embed secrets in code or logs.
- Do not assume Prisma or any ORM unless explicitly part of the stack.

Recommended Project Structure

src/
  app/
    page.tsx
    /api/
      auth.ts
      posts.ts
  components/
    Layout.tsx
    PostCard.tsx
  lib/
    db.ts
  db/
    migrations/
      001_init.sql
  tests/
    unit/
      example.test.ts
    integration/
      api.test.ts

Core Engineering Principles

• Explicit contracts between frontend and backend via typed DTOs.
• Small, testable units with deterministic behavior.
• Security-first by default: validate input, sanitize output, and restrict access.
• Clear separation of concerns between UI, data access, and business logic.
• Config-driven and reproducible deployments across environments.

Code Construction Rules

• Use TypeScript end-to-end with strict mode enabled.
• Frontend pages in src/app; API handlers in src/app/api or /pages/api as appropriate.
• Database access via node-postgres (pg) with a connection Pool; never string-join SQL queries.
• Input validation on both client and server; use Zod for runtime validation and TypeScript for types.
• API routes should return structured responses with explicit status codes.
• Do not hardcode credentials; use environment variables and secret management.

Security and Production Rules

• Use HttpOnly cookies for sessions; implement CSRF protection on state-changing endpoints.
• Configure TLS, secure headers, and Content Security Policy in production.
• Enable database connection limits and proper timeouts.
• Do not expose query strings or error stacks to clients.

Testing Checklist

• Unit tests for utilities, schemas, and helpers.
• Integration tests for database interactions with a test database.
• API tests that cover success and error paths; include authentication scenarios.
• End-to-end tests for critical user journeys using a headless browser.
• CI pipeline gates for lint, type-check, unit tests, and integration tests.

Common Mistakes to Avoid

• Assuming ORM is always required; prefer raw queries for performance and control when using PostgreSQL.
• Baking secrets into client bundles or version control.
• Overreliance on client-side validation; enforce server-side validation too.
• Skipping migrations or duplicating migrations across environments.

FAQ

What is this CLAUDE.md Template for?

A copyable Claude Code blueprint for a production-ready Next.js + PostgreSQL app, with a ready-to-paste CLAUDE.md template and stack-specific rules.

Which stack does this template cover?

Next.js with PostgreSQL, using a minimal data layer and direct pg client access.

How do I configure the PostgreSQL connection?

Set environment variables (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME) and use a TLS-enabled connection; never commit credentials.

How do I run tests and deploy?

Run unit and integration tests locally; deploy to Vercel or a container-based host; wire env vars in production.

What about security?

Use HttpOnly cookies, CSRF protection, TLS, parameterized queries, and input sanitization; avoid leaking secrets.