Skip to content
STACK IT FAST
Share

Next.js 16 + Drizzle ORM + Supabase

Curated rule SaaS / Web App Updated Oct 2026 Which file does my tool read?
nextjs-drizzle-supabase.md

Production guidelines for Next.js App Router, Drizzle ORM with postgres-js, Supabase Transaction Pooler (prepare: false), and RLS security.

Next.js Drizzle Supabase TypeScript Tailwind CSS PostgreSQL
Formats
4 files
AGENTS.md
59 lines
CLAUDE.md
16 lines
Languages
TypeScript
Updated
Oct 2026
Used by
4 projects
Install

Writes .claude/skills/nextjs-drizzle-supabase/SKILL.md

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

Rule files

AGENTS.md· 59 lines · 3.9 KB
1# Project Architecture & Guidelines (Next.js + Drizzle + Supabase)
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 via Supabase, typed schema managed with Drizzle ORM (`drizzle-orm`, `drizzle-kit`, `postgres-js`).
7- **Auth & Storage**: Supabase Auth (`@supabase/ssr` cookie handler) and Supabase Storage.
8- **Connection Pooling**: Supabase Transaction Pooler (port 6543) via `postgres-js`.
9
10## 2. Database Connection Rules (Critical Supabase Pooler Gotcha)
11- When connecting to Supabase's Transaction Pooler (port 6543), prepared statements MUST be disabled (`prepare: false`). Otherwise queries will fail with `prepared statement "drizzle_s_1" already exists`.
12- Always implement the singleton connection pattern in `src/db/index.ts`:
13 ```typescript
14 import { drizzle } from 'drizzle-orm/postgres-js';
15 import postgres from 'postgres';
16 import * as schema from './schema';
17
18 const connectionString = process.env.DATABASE_URL!;
19 const globalForDb = globalThis as unknown as { conn: postgres.Sql | undefined };
20
21 const client =
22 globalForDb.conn ??
23 postgres(connectionString, {
24 prepare: false, // REQUIRED for Supabase Transaction Pooler (:6543)
25 max: process.env.NODE_ENV === 'production' ? 10 : 1,
26 });
27
28 if (process.env.NODE_ENV !== 'production') globalForDb.conn = client;
29
30 export const db = drizzle(client, { schema });
31 ```
32- For Drizzle Kit migrations, provide the direct PostgreSQL connection URL (`DIRECT_URL` on port 5432) in `drizzle.config.ts`.
33
34## 3. Schema Organization & Relational Queries
35- Group modular tables in `src/db/schema/` (e.g., `users.ts`, `posts.ts`, `auth.ts`).
36- Define explicit relations in `src/db/schema/relations.ts` using `relations()` from `drizzle-orm`.
37- Use Drizzle Relational Queries (`db.query.<table_name>.findFirst({ with: { ... } })`) for typed nested fetches without manual joins.
38
39## 4. Server Actions & Mutations
40- Place server actions in `src/actions/` with `'use server'` at the top.
41- Validate all inputs using `zod` schemas before executing database queries.
42- Authenticate the calling session using Supabase SSR client before executing privileged operations.
43
44## 5. Common Pitfalls to Avoid
45- ❌ Forgetting `prepare: false` on Supabase pooled connections.
46- ❌ Running `drizzle-kit push` against production databases; always use generated SQL migrations (`drizzle-kit generate` & `drizzle-kit migrate`).
47- ❌ Fetching data in client component `useEffect`; fetch in React Server Components or Server Actions.
48
49## 6. Testing Conventions
50- Use Vitest for unit tests on Server Actions and Drizzle query helpers; mock the `db` singleton with a test-only in-memory or containerized Postgres.
51- Use Playwright for e2e coverage of auth flows (Supabase SSR cookie handling is easy to break silently across route handler changes).
52- Test RLS policies directly with SQL assertions against a Supabase local dev instance — application-level tests alone won't catch a missing policy.
53- Run `tsc --noEmit` as a required check; Drizzle's inferred types catch most schema/query mismatches before runtime.
54
55## 7. Git Workflow & PR Conventions
56- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the route or table, e.g. `fix(db): add missing index on posts.author_id`.
57- Generated Drizzle migrations (`drizzle-kit generate`) ship in the same PR as the schema change; never hand-edit generated SQL.
58- Require `tsc --noEmit` and `bun run build` green before merge — a broken Server Action fails silently in dev but hard in production.
59- Squash-merge; never `drizzle-kit push` directly against a shared or production database from a feature branch.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Standardized production guidelines for Next.js 16 App Router, Drizzle ORM, and Supabase PostgreSQL.

Verified Real-World Adoption

Utilized by modern high-velocity platforms like Supabase Studio, Dub.co, and CopilotKit.

Key Architectural Nuances

  • Prepared Statement Disabling: Supabase’s transaction pooler requires prepare: false to prevent statement naming collisions across ephemeral Lambda invocations.
  • Relational Query Builder: Combines SQL performance with declarative, type-safe nested object queries.

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 Supabase's transaction pooler require prepare: false?

PgBouncer's transaction pooling mode reassigns the underlying Postgres connection after every transaction, but prepared statements are tied to a specific connection. When postgres-js tries to reuse a prepared statement name on a connection that doesn't have it, Postgres throws a 'prepared statement already exists' or 'does not exist' error — disabling prepared statements avoids the mismatch entirely.

Why use a globalThis singleton for the Drizzle client instead of creating it per request?

Next.js hot module reloading in development re-executes module-level code on every file save, which would otherwise open a fresh Postgres connection each time and quickly exhaust the connection pool. Caching the client on globalThis in development ensures the same connection is reused across HMR reloads.

Used in production

Explore all stacks

Supabase Studio

1
Developer Tool · 20+ people

Centering the developer experience around PostgreSQL allows Supabase Studio to provide spreadsheet-like table editing and SQL execution directly on production databases.

Payload CMS

Next.js-Native Headless CMS & App Framework · 6-20 people

A pnpm and Turborepo monorepo lets one core package share a common database-adapter export shape across MongoDB, Postgres, SQLite, and D1, while GraphQL, storage providers, and deployment templates stay in separate packages so a project only pulls in the pieces its target host and database actually need.

shadcn/ui

Copy-Paste UI Component Architecture · 1M+ MAU

Distributing components as source code gives developers full ownership and customization freedom while pairing Radix accessibility with Tailwind utility styling.

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 · MVP · SaaS
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 · PostgreSQLfastapi-python-postgres/AGENTS.mdFastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)FastAPI · Python · PostgreSQLnestjs-postgres-redis/AGENTS.mdNestJS + PostgreSQL + Redis + BullMQNestJS · Node.js · TypeScriptnextjs-ai-sdk-jev/AGENTS.mdNext.js + Vercel AI SDK + Jev (System One + LLM)Next.js · React · TypeScript