STACK IT FAST
ALL RULES & SKILLS

Next.js 15 + Prisma ORM + PostgreSQL

Raw .MD nextjs-prisma-postgres
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

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

Architecture Overview

Production conventions for building high-scale full-stack applications with Next.js 15 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.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills
4 FILE FORMATS Django, Python

Django + PostgreSQL + Redis + Celery

Production guidelines for Django 5 enterprise applications, PostgreSQL connection pooling, Redis caching, and Celery async workers.

6 techs Copy Rules
4 FILE FORMATS FastAPI, Python

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Production guidelines for FastAPI, Pydantic v2 validation, Async SQLAlchemy 2.0 (asyncpg), Alembic migrations, and PostgreSQL/Redis.

7 techs Copy Rules
4 FILE FORMATS Laravel, Livewire

Laravel + Livewire + PostgreSQL

Production guidelines for Laravel 11 monoliths, Livewire reactive components, Eloquent ORM query discipline, and queued job workers.

6 techs Copy Rules
4 FILE FORMATS NestJS, Node.js

NestJS + PostgreSQL + Redis + BullMQ

Enterprise backend architecture guidelines for NestJS modular design, PostgreSQL connection pooling, Redis BullMQ background jobs, and DTO validation.

6 techs Copy Rules