Cursor rules for Next.js + Supabase: a free starter guide

Updated October 15, 2026

If you build a Next.js + Supabase app with Cursor, the agent keeps making the same mistakes: getSession() on the server, tables without Row Level Security, the service-role key imported into a Client Component, Stripe webhooks parsed with req.json(). Cursor project rules fix that by giving the agent your conventions on every request. This guide shows how to set them up and gives you free rules to copy.

Where Cursor rules live

Project rules are .mdc files in .cursor/rules/ at your project root (the folder with package.json). Each file starts with YAML frontmatter:

---
description: Supabase clients, migrations and Row Level Security
globs: src/lib/supabase/**,supabase/**,src/middleware.ts
alwaysApply: false
---

• alwaysApply: true: loaded on every request. Use it for core stack conventions and security.
• globs: loaded when matching files are in context, such as Supabase rules when you touch supabase/**.
• description: lets the agent pull the rule in when it thinks it is relevant.

Folders starting with a dot are hidden. On a Mac, press Cmd + Shift + . in Finder to see .cursor. Check your rules are picked up in Cursor Settings → Rules.

A layout that works for Next.js + Supabase

.cursor/rules/
  00-core.mdc       # alwaysApply: stack + conventions
  10-supabase.mdc   # globs: src/lib/supabase/**, supabase/**
  20-auth.mdc       # globs: src/app/login/**, src/app/auth/**
  30-stripe.mdc     # globs: src/app/api/stripe/**
  40-security.mdc   # alwaysApply: guardrails
AGENTS.md           # same rules for Codex, Copilot, Windsurf
CLAUDE.md           # @AGENTS.md for Claude Code

Free rule 1: core Next.js 15 conventions

---
description: Core conventions for Next.js 15 App Router + Supabase
alwaysApply: true
---
- Next.js 15 App Router, React 19, TypeScript strict, @supabase/ssr, zod.
- Default to Server Components. Add "use client" only for state, effects or browser APIs.
- Mutations go through Server Actions or Route Handlers.
- Validate every external input (form data, params, JSON, webhooks) with zod.
- In Next 15, cookies(), headers(), params and searchParams are async: always await them.
- Don't create SDK clients that read env vars at module top level in route files.
- Run npm run build after every feature. Not done until the build passes.

Free rule 2: Supabase clients and auth checks

---
description: Supabase clients and auth
globs: src/lib/supabase/**,src/middleware.ts,src/app/**/actions.ts
alwaysApply: false
---
- Use @supabase/ssr: createBrowserClient in client.ts, createServerClient with
  cookies { getAll, setAll } from await cookies() in server.ts.
- Never use the deprecated @supabase/auth-helpers-nextjs or get/set/remove cookies.
- On the server, authorize with supabase.auth.getUser(), never getSession().
- The service-role client lives in admin.ts with import "server-only" and is used
  only in webhooks/cron.

Free rule 3: Row Level Security

- Every table in public enables RLS in the same migration that creates it.
- One policy per operation (select/insert/update/delete), using (select auth.uid()).
- Update policies need both using and with check.
- Never authorize with user_metadata (users can edit it).
- Test every policy change as two different users.

More detail and SQL in Supabase RLS for vibe coders.

Free rule 4: Stripe webhooks

- Webhook route: export const runtime = "nodejs"; read the raw body with await req.text();
  verify with stripe.webhooks.constructEvent. Return 400 on failure.
- The webhook is the source of truth. Never grant access on the success page.
- Handle checkout.session.completed, customer.subscription.updated and .deleted.
- Make handlers idempotent: store processed event ids.

Why each line matters: Stripe webhooks in the Next.js App Router.

Free rule 5: security guardrails

---
description: Security guardrails for every change
alwaysApply: true
---
- Never commit or print secrets. Only NEXT_PUBLIC_* vars may reach the browser.
- Every Server Action and Route Handler: authenticate (getUser), authorize
  (ownership), validate (zod). In that order.
- Redirect targets must be relative paths: reject //, backslashes, % and @.

Tips so the agent actually follows them

• Write imperatives with concrete names ("use getUser()") instead of vague goals ("handle auth securely").
• Keep each file focused and scoped with globs so context stays small.
• Add a definition of done: npm run build passes.
• Mirror the rules in AGENTS.md and make CLAUDE.md import it, so every agent gets the same instructions. See Cursor rules vs AGENTS.md vs CLAUDE.md.

Want the complete, build-tested set?

The rules above are shortened. Pack #1: Next.js + Supabase SaaS Starter ($19) has the full five rules, AGENTS.md, CLAUDE.md, a 10-step prompt playbook, a security checklist and reference code (Supabase clients, middleware, auth with safe redirects, Stripe Checkout + webhook + Customer Portal, RLS migrations, and RLS and redirect test scripts).

See what's in Pack #1