Next.js 16 + Prisma ORM + PostgreSQL

Curated rule SaaS / Web App Updated Oct 2026 Which file does my tool read?

Production guidelines for Next.js App Router, Server Actions, Prisma connection pooling, PgBouncer/Neon tuning, and Zod schema validation.

Next.js Prisma PostgreSQL TypeScript Tailwind CSS

Formats: 4 files
AGENTS.md: 56 lines
CLAUDE.md: 17 lines
Languages: TypeScript
Updated: Oct 2026
Used by: 4 projects

Install

Writes .claude/skills/nextjs-prisma-postgres/SKILL.md

$ curl -s --create-dirs -o .claude/skills/nextjs-prisma-postgres/SKILL.md https://stackitfast.com/rules/nextjs-prisma-postgres/SKILL.md

Rule files

AGENTS.md· 56 lines · 3.7 KB

1	# Project Architecture & Guidelines (Next.js 16 + Prisma + PostgreSQL)
2
3	## 1. System Architecture
4	- Framework: Next.js 16 (App Router, Server Components by default).
5	- Next.js 16 specifics: request APIs (`cookies()`, `headers()`, `params`, `searchParams`) are async, so always `await` them; request interception lives in `proxy.ts` (the renamed `middleware.ts`); Turbopack is the default bundler for dev and build.
6	- Database & ORM: PostgreSQL with Prisma ORM (`@prisma/client`, `prisma`).
7	- Connection Pooling: PgBouncer / Neon pooled connection string on port 6543 (`pgbouncer=true&connection_limit=1` for serverless Lambdas).
8	- Validation & Types: TypeScript (strict mode) + Zod for runtime schema validation.
9
10	## 2. Prisma Client & Connection Management (Critical)
11	- Always implement the global singleton pattern in `src/lib/prisma.ts` to prevent connection exhaustion during development HMR:
12	```typescript
13	import { PrismaClient } from '@prisma/client';
14
15	const globalForPrisma = globalThis as unknown as { prisma: PrismaClient \| undefined };
16
17	export const prisma =
18	globalForPrisma.prisma ??
19	new PrismaClient({
20	log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
21	});
22
23	if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
24	```
25	- Never call `$connect()` or `$disconnect()` manually inside Server Actions or route handlers.
26	- In production serverless environments, tune `connection_limit=1` or `connection_limit=2` in `DATABASE_URL`.
27	- Use `DIRECT_URL` (direct port 5432) for running migrations via `prisma migrate deploy`.
28
29	## 3. Server Actions & Mutations
30	- Place server mutations in `src/actions/` with `'use server'` directive.
31	- Parse and validate all inputs with Zod before executing Prisma queries.
32	- Return typed result objects: `{ success: true, data: T } \| { success: false, error: string }`.
33	- Keep client components minimal; fetch data in React Server Components (RSC) and pass down as props.
34
35	## 4. Migration & Schema Workflow
36	- Schema source of truth: `prisma/schema.prisma`.
37	- Development: Run `bunx prisma migrate dev --name <migration_name>`.
38	- Production CI/CD: Run `bunx prisma migrate deploy`. NEVER use `db push` in production.
39	- Indexes: Explicitly define indexes (`@@index([userId, createdAt])`) for all foreign keys and frequently queried fields.
40
41	## 5. Common Pitfalls to Avoid
42	- ❌ Over-fetching: Avoid unconstrained `findMany()`; always pass `select` or `take` / `skip` pagination.
43	- ❌ N+1 Queries: Use Prisma `include` or batch queries instead of executing queries in loops.
44	- ❌ Exposing Database Secrets: Never prefix `DATABASE_URL` with `NEXT_PUBLIC_`.
45
46	## 6. Testing Conventions
47	- Use Vitest for unit tests on Server Actions; point the test Prisma client at a disposable schema or Docker Postgres instance, never a shared dev database.
48	- Use Playwright for e2e coverage of critical mutation flows (checkout, auth, billing) end-to-end through the real UI.
49	- Test Zod validation boundaries on every Server Action input schema — this is the first and cheapest layer to catch bad data.
50	- Run `bunx prisma validate` and `tsc --noEmit` in CI to catch schema/query drift before it reaches a migration.
51
52	## 7. Git Workflow & PR Conventions
53	- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the model or route, e.g. `fix(orders): prevent duplicate submission on double-click`.
54	- `prisma/migrations/` files ship in the same PR as the `schema.prisma` change that generated them — never hand-edit a generated migration.
55	- Require `tsc --noEmit` and `bun run build` green before merge.
56	- Never merge a PR containing `prisma db push` in its history against a shared environment; migrations only.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Production conventions for building high-scale full-stack applications with Next.js 16 App Router, Prisma ORM, and PostgreSQL.

Verified Real-World Adoption

This exact architecture is deployed in production by top open-source platforms including Cal.com, Documenso, Papermark, Typebot, Formbricks, and Umami.

Key Architectural Nuances

Serverless Connection Management: Using globalThis singleton client prevents Lambda / HMR connection pool leakage.
Migration Isolation: Separating DATABASE_URL (pooled port 6543) from DIRECT_URL (migration port 5432) ensures atomic DDL schema updates.

Frequently asked questions

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Why does Prisma need a globalThis singleton in Next.js?

Next.js hot module reloading re-executes module code on every save in development, and without caching the client on globalThis, each reload would instantiate a new PrismaClient and open a fresh connection pool. Left unchecked this exhausts the database's max_connections within a few dozen saves during a normal dev session.

Why use prisma migrate deploy instead of db push in production?

db push directly syncs your schema to the database with no migration history, no rollback path, and no review artifact — it's designed for rapid prototyping, not production changes. migrate deploy applies pre-generated, reviewable SQL migration files in order, giving you an auditable history and the ability to roll back a specific change.

Used in production

Explore all stacks

Cal.com

Scheduling SaaS · 6-20 people

Splitting the tRPC-based web app from an independently versioned NestJS Platform API lets Cal.com serve both its own product and third-party developers from one monorepo, while Turborepo and per-integration app-store packages keep dozens of calendar/payment providers buildable and testable in isolation.

tRPC

End-to-End Typesafe API Framework · 1M+ MAU

tRPC connects backend procedure implementations directly to frontend React hooks with zero-boilerplate type inference.

Prisma

Next-Generation Node.js & TypeScript ORM · 1M+ MAU

Declarative schema modeling combined with modular driver adapters allows Prisma to generate fully type-safe database clients that run consistently from Node servers to edge runtimes.

Next.js

Fullstack React Framework · 1M+ MAU

Performance-critical compilation and bundling are implemented as Rust crates (Turbopack, SWC transforms) compiled to native addons, while the framework surface stays in TypeScript, letting Next.js run its full test matrix across three interchangeable bundlers without forking the codebase.

Where this stack fits

Stack It First recommends it at:

Web · Growth · SaaS Web · Scale · SaaS Web · Scale · SEO-driven

Walk the web roadmap

Every stack ships as files

More AI agent coding rules and skills

View all

django-postgres-redis/AGENTS.mdDjango + PostgreSQL + Redis + CeleryDjango · Python · PostgreSQL fastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQL nestjs-postgres-redis/AGENTS.mdNestJS + PostgreSQL + Redis + BullMQNestJS · Node.js · TypeScript nextjs-ai-sdk-jev/AGENTS.mdNext.js + Vercel AI SDK + Jev (System One + LLM)Next.js · React · TypeScript