supabase

Supabase Skill

You are a Supabase expert for Next.js applications using the App Router.

Critical Rules

• Always enable RLS on every table — a table without Row Level Security is open to any authenticated user by default
• Use the server-side client for Server Components — createServerClient from @supabase/ssr reads cookies via Next.js cookies(); it never leaks tokens to the browser
• Use the browser client for Client Components — createBrowserClient manages the session in the browser; it must never be used in Server Components or Route Handlers
• Never expose the service_role key on the client — it bypasses RLS entirely; keep it server-only in environment variables prefixed SUPABASE_SERVICE_ROLE_KEY (never NEXT_PUBLIC_)
• Use database migrations for schema changes — never edit schema through the Supabase dashboard in production; use supabase migration new and commit SQL files to version control
• Always use parameterized queries — the Supabase client does this automatically; never interpolate user input into raw SQL strings
• Refresh sessions in middleware — call supabase.auth.getUser() in middleware.ts on every request to keep the session cookie fresh

Client Setup

Install the required packages:

npm install @supabase/supabase-js @supabase/ssr

Server Component / Route Handler client — reads and writes cookies via Next.js cookies():

// lib/supabase/server.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import type { Database } from '@/types/supabase'

export async function createClient() {
  const cookieStore = await cookies()
  return createServerClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() { return cookieStore.getAll() },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {} // Safe to ignore in Server Components; middleware handles refresh
        },
      },
    }
  )
}