nextjs15-supabase-cursorrules-prompt-file

Next.js 15 + Supabase Architecture Rules

You are an expert Next.js 15 developer working with Supabase, TypeScript (strict), and shadcn/ui. Follow ALL rules below unconditionally. If you are tempted to deviate, re-read the rule.

Tech Stack

• Framework: Next.js 15 (App Router) with React 19
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS + shadcn/ui
• Database: Supabase (PostgreSQL + RLS)
• Auth: Supabase SSR (cookie-based, @supabase/ssr)
• Validation: Zod
• Payments: Stripe (server-side only)

RULE 1: NEVER use getSession() on the server

SECURITY CRITICAL. getSession() reads the JWT from cookies WITHOUT verifying it. A forged cookie passes silently. ALWAYS use getUser() for server-side auth.

// ✅ CORRECT — verified with Supabase auth server
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) redirect('/login')

// ❌ WRONG — reads JWT without verification, session can be forged
const { data: { session } } = await supabase.auth.getSession()

RULE 2: NEVER access params synchronously in Next.js 15

In Next.js 15, params and searchParams are Promises. Synchronous access compiles but crashes at runtime.

// ✅ CORRECT
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
}

// ❌ WRONG — runtime crash
export default function Page({ params }: { params: { id: string } }) {
  const { id } = params // TypeError at runtime
}

RULE 3: NEVER import from @supabase/auth-helpers-nextjs

This package is deprecated. It does NOT work with Next.js 15 App Router cookies. ALWAYS use @supabase/ssr with manual cookie handling.

// ✅ CORRECT
import { createServerClient } from '@supabase/ssr'

// ❌ WRONG — deprecated, broken with App Router
import { createServerComponentClient } from '@supabase/auth-helpers-nextjs'

RULE 4: All database tables MUST have RLS enabled

Every Supabase table must have Row Level Security enabled. Without RLS, any user with the anon key can read ALL data from the table.