CLAUDE.md Template — Next.js 16 App Router + PostgreSQL + NextAuth.js + Prisma Starter Stack

Overview

This CLAUDE.md Template targets a production-ready starter stack: Next.js 16 App Router with an app directory, PostgreSQL as the database, NextAuth.js (Auth.js) for authentication, and Prisma as the ORM. It provides a copyable CLAUDE.md template designed for Claude Code workflows to rapidly scaffold, secure, and deploy a modern full-stack app.

Direct answer: The template gives you a ready-to-paste CLAUDE.md block that enforces stack-aware rules, promotes best practices, and reduces setup boilerplate for the specified stack.

When to Use This CLAUDE.md Template

• Starting a new Next.js 16 App Router project with PostgreSQL and Prisma.
• Setting up authentication using NextAuth.js (Auth.js) with JWT sessions.
• Creating a reproducible CLAUDE.md workflow for Claude Code-driven implementations.
• Prototyping secure API routes and middleware in App Router.
• Sharing a consistent starter pattern with teammates or open-source collaborators.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a precision-engineered starter for Next.js 16 App Router + PostgreSQL + NextAuth.js (Auth.js) + Prisma. Produce a complete, copyable CLAUDE.md template tailored to this stack.

Architecture rules:
- Use Next.js 16 App Router with the app directory
- PostgreSQL as the primary database; Prisma as the ORM
- NextAuth.js configured for JWT sessions
- Separate server and client concerns; server components by default; client components only when necessary
- Use environment-based configuration; secrets via environment variables

File structure rules:
- Keep the solution compact and repo-friendly: prisma/, app/, lib/, and prisma/seed.ts at the top level
- Prisma schema in prisma/schema.prisma; seeds in prisma/seed.ts
- Auth logic under app/(auth) and lib/ for shared utilities

Authentication rules:
- Implement NextAuth.js with JWT sessions and Credentials provider for initial login
- Protect routes with middleware.ts in app/middleware.ts
- Use secure cookies (HttpOnly, Secure, SameSite=Lax/Strict)

Database rules:
- PostgreSQL database defined in DATABASE_URL
- Prisma models: User, Account, Session, VerificationToken
- Unique indices on user email and provider accounts
- Avoid hard-coded credentials; rely on env vars

Validation rules:
- Use zod for input validation in API routes
- Validate all critical inputs on the server; surface friendly errors for clients

Security rules:
- Never store plaintext passwords; hash with bcrypt or argon2
- Do not expose secrets in code or logs
- Enforce CSRF protection for non-GET API routes
- Do not bypass authentication or authorization checks

Testing rules:
- Unit tests for utility functions and validators
- Integration tests for auth flows and Prisma interactions
- End-to-end checks for onboarding and protected routes where feasible

Deployment rules:
- Run Prisma migrate on deploy; manage migrations in CI/CD
- Use separate dev/prod databases; configure via DATABASE_URL variants
- Secrets managed by hosting provider; avoid leaking in logs or code
- Build and deploy with Vercel or a Node.js environment supporting edge/serverless

Things Claude must not do:
- Do not bypass authentication or authorization checks
- Do not access non-production endpoints from production
- Do not modify database without a proper Prisma migration

Recommended Project Structure

project-root/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── components/
│       ├── Header.tsx
│       └── AuthProvider.tsx
├── lib/
│   ├── db.ts
│   └── auth.ts
├── prisma/
│   ├── schema.prisma
│   └── seed.ts
├── seeds/
│   └── seed.ts
└── README.md

Core Engineering Principles

• Type safety and clarity: TypeScript across server and client with strict mode
• Explicit architectural boundaries: app router UI, API interactions, and data layer separated
• Prisma discipline: well-defined schema, migrations, and seed data
• Environment-driven configuration: avoid hard-coded values, rely on env vars
• Security-first by default: proper authentication, authorization, and secrets handling

Code Construction Rules

• Use TypeScript everywhere; enable strict mode and noImplicitAny
• Leverage App Router features: server components by default; client components only when needed
• API routes should validate input with zod and handle errors gracefully
• Prisma schema must align with PostgreSQL capabilities (constraints, indices)
• Keep dependencies minimal and aligned with the stack
• Do not use non-production endpoints or credentials in code

Security and Production Rules

• Store secrets in a secure vault or environment variables; never commit them
• Use secure cookies for NextAuth.js sessions; set HttpOnly, Secure, SameSite appropriately
• Enable CSRF protection for non-idempotent operations
• Enforce role-based access control on protected routes
• Audit logs for authentication attempts and critical actions

Testing Checklist

• Unit tests for utilities and validators
• Integration tests for auth flows (login, signup, e2e session refresh)
• Prisma data layer tests for basic CRUD constraints
• End-to-end checks for protected routes and signup flow where feasible
• CI/CD tests to verify migrations run and app boots with env vars

Common Mistakes to Avoid

• Introducing production secrets into code or commits
• Overexposing API routes without proper authorization
• Using client-side only validation without server validation
• Ignoring database migrations in production deployments

FAQ

What is a CLAUDE.md Template?

A copyable CLAUDE.md template page that provides Claude Code-ready instructions for a specific stack.

Which stack is covered by this CLAUDE.md Template?

Next.js 16 App Router + PostgreSQL + NextAuth.js (Auth.js) + Prisma ORM starter stack.

Where should I paste the CLAUDE.md template content?

Paste into a CLAUDE.md file at the root of your project or in your Claude Code workflow repository.

How do I customize database connection details?

Edit the .env file with DATABASE_URL and adjust prisma/schema.prisma accordingly.

What should I do about secrets in CLAUDE.md templates?

Avoid plaintext secrets; use environment variables and secret managers.