awesome-nextjs-supabase: Instructions file for Codex

AGENTS.md — Next.js + Supabase Production Rules

Drop-in guardrails for AI coding agents (Cursor, GitHub Copilot, Claude Code, Windsurf, and any tool that reads AGENTS.md) working on a Next.js (App Router) + Supabase + Stripe project.

AI tools confidently generate code that works on localhost and silently breaks in production — empty RLS results, lost SSR sessions, redirect loops, duplicate Stripe charges, stale UI after mutations. These rules encode the fixes for the most common failures, mapped to the Production Incident Index.

How to use: copy this file (and .cursor/rules/) into your own repo root. Most agents read AGENTS.md automatically; Cursor reads .cursor/rules/*.mdc.

---

Auth and Sessions

• Always await cookies() in the App Router. Reading cookies synchronously throws the cookies() should be awaited warning and breaks server rendering. (INC-001)
• Never protect /auth/callback or the login route in middleware. If the matcher covers them, OAuth loops back to login forever. Exclude callback and login paths explicitly. (INC-004)
• Use the @supabase/ssr client on the server, not the browser client. The SSR client must read and write cookies, or the session vanishes on refresh. Verify cookie domain matches across prod and preview deployments. (INC-005)
• Refresh the session in middleware by passing cookies through both request and response. A missing refresh path is the #1 cause of "logged out after reload."

Middleware

• Scope the matcher narrowly. Never let it match _next/static, _next/image, favicons, or other public assets — it breaks static delivery and adds latency. Exclude them with a negative-lookahead matcher. (INC-014)
• Middleware runs on the Edge runtime. Do not use Node-only APIs there.

Row Level Security (RLS)

• Enabling RLS without a SELECT policy returns an empty array, not an error. If queries silently return [] for rows that exist, the policy is missing — not the data. Add scoped policies per role and test with both anon and authenticated clients. (INC-002)
• Never write a policy that queries its own table through nested EXISTS — it causes infinite recursion. Move the check into a SECURITY DEFINER helper function or a separate table/view. (INC-003)
• Index every column used in a policy predicate (user_id, tenant_id, org_id). Unindexed predicates turn RLS into a full scan and make the API unusably slow. Validate with EXPLAIN ANALYZE. (INC-015)
• Wrap auth.uid() in a SELECT ((SELECT auth.uid())) inside policies so Postgres caches it per-statement instead of per-row.