Full Stack · Cursor Rules

Supabase + Next.js Rules

Cursor rules for Supabase + Next.js App Router. Client separation, RLS, auth middleware, server actions for mutations.

Supabase · Next.js

What it does

Teaches Cursor the client/server separation Supabase requires: @supabase/ssr in server components and route handlers, @supabase/supabase-js only in client components, never the service_role key on the client, middleware.ts refreshing sessions on every request, and RLS enabled on every table with policies referencing auth.uid() and organization_id.

What it solves

Most Supabase + Next.js bugs come from mixing client and server Supabase clients or disabling RLS during development and forgetting to re-enable it. These rules prevent both classes of mistake.

How to install

Which tool are you using?

Not sure? Claude.ai is the website. Claude Code is the command-line tool you install separately. Cursor is a code editor that reads .cursorrules.

01
Copy the rules
Click the Copy button on the code block below to grab the full contents of .cursorrules.
02
Create .cursorrules at your project root
Cursor reads .cursorrules from the top-level folder of your project. Paste the copied content there.
terminalshell
1touch .cursorrules
03
Reload Cursor
Cmd+Shift+P → "Developer: Reload Window". Cursor picks up the new rules immediately.
04
Verify with a test prompt
Ask Cursor to generate a component or function in your stack. The output should follow the conventions in your rules file.

The cursor rules file

Copy the full contents below, or download the file directly.

.cursorrules

.cursorrulestext

1# Supabase + Next.js Cursor Rules2 3You are an expert building full-stack apps with Supabase + Next.js App Router.4 5## Client Separation6- @supabase/ssr for server components and route handlers7- @supabase/supabase-js for client components only8- Never import service_role key on the client9- One createClient util per context (server, client, middleware)10 11## Auth12- Use middleware.ts to refresh sessions on every request13- Protect routes by checking user in server components14- Sign-in, sign-up, magic-link flows via Supabase auth15- Never trust client-only auth state for authorization16 17## RLS18- RLS enabled on every table — no exceptions19- Policies reference auth.uid() and organization_id20- Never disable RLS in prod to "just fix it"21- Test policies with anon key in staging22 23## Data24- Typed queries via supabase-js generics25- Generate types with supabase gen types typescript26- Server Actions for mutations, not client writes27- Realtime subscriptions from client components only28 29## Storage30- Signed URLs for private buckets31- Public buckets only for truly public assets32- Image transform + caching via Next.js Image

Example output

What Claude does before and after you install this cursor rules.

Without this cursor rules

Cursor imports service_role in a client component, disables RLS to fix a query, and writes mutations from the client.

With this cursor rules

Cursor keeps service_role server-only, writes mutations as Server Actions, generates typed queries, and tests RLS policies before shipping.

Customization tips

For projects that use Supabase but not Next.js, remove the Next.js-specific middleware rule. For orgs without multi-tenancy, drop organization_id from the RLS section. If you use Drizzle with Supabase, add a Drizzle-specific section to replace supabase-js for reads.