name: supabase-setup description: Initialize Supabase for a project including database schema, Row Level Security policies, authentication, storage buckets, and edge functions. Use when user says "set up Supabase", "add Supabase", "configure database", "add auth", "Supabase init", "RLS policies", or needs a backend with Supabase. user-invokable: true args:

• name: target description: What to set up (auth, storage, schema, all) (optional) required: false metadata: author: builder-skills version: "1.0.0"

Supabase Setup

Initialize and configure Supabase for a project. If target is provided, focus on that area (auth, storage, schema). Default to "all" if omitted.

Step 1: Install and Initialize

pnpm add @supabase/supabase-js
pnpm add -D supabase
npx supabase init

This creates a supabase/ directory with config and a migrations/ folder.

Link to a remote project (ask the user for their project ref if not provided):

npx supabase link --project-ref <project-ref>

Step 2: Environment Variables

Add to .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon-key>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>

Step 3: Create the Supabase Client

Create src/lib/supabase/client.ts (browser client):

import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  )
}

Create src/lib/supabase/server.ts (server client):

import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export async function createClient() {
  const cookieStore = await cookies()
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value, options }) =>
            cookieStore.set(name, value, options),
          )
        },
      },
    },
  )
}

Install the SSR helper:

pnpm add @supabase/ssr

Step 4: Schema Design (Migrations)

Create migrations with:

npx supabase migration new <migration-name>

Follow these conventions in every migration:

• Use uuid for primary keys: id uuid default gen_random_uuid() primary key
• Add timestamps to every table: created_at timestamptz default now() not null, updated_at timestamptz default now() not null
• Use snake_case for all table and column names
• Use plural table names (users, posts, comments)
• Always enable RLS: alter table <table> enable row level security;

Apply migrations locally:

npx supabase db reset   # Resets local DB and applies all migrations

Push to remote:

npx supabase db push

Step 5: Row Level Security (RLS)

Enable RLS on every table. Never leave a table without policies in production.

Common RLS Patterns

Example: Owner-based CRUD

-- Users can read their own rows
create policy "Users read own data"
  on profiles for select
  using (auth.uid() = user_id);

-- Users can insert their own rows
create policy "Users insert own data"
  on profiles for insert
  with check (auth.uid() = user_id);

-- Users can update their own rows
create policy "Users update own data"
  on profiles for update
  using (auth.uid() = user_id)
  with check (auth.uid() = user_id);

-- Users can delete their own rows
create policy "Users delete own data"
  on profiles for delete
  using (auth.uid() = user_id);

Example: Org-based Access

create policy "Org members can read"
  on projects for select
  using (
    exists (
      select 1 from org_members
      where org_members.org_id = projects.org_id
        and org_members.user_id = auth.uid()
    )
  );

Example: Role-based Access

create policy "Admins can do anything"
  on settings for all
  using (
    exists (
      select 1 from user_roles
      where user_roles.user_id = auth.uid()
        and user_roles.role = 'admin'
    )
  );

Step 6: Authentication

Email + Password

Enabled by default. Create sign-up and login flows:

// Sign up
const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'securepassword',
})

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'securepassword',
})

OAuth Providers

Enable in Supabase Dashboard > Authentication > Providers. Common setup:

const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google', // or 'github', 'apple', etc.
  options: {
    redirectTo: `${window.location.origin}/auth/callback`,
  },
})

Create an auth callback route at src/app/auth/callback/route.ts:

import { NextResponse } from 'next/server'
import { createClient } from '@/lib/supabase/server'

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url)
  const code = searchParams.get('code')

  if (code) {
    const supabase = await createClient()
    await supabase.auth.exchangeCodeForSession(code)
  }

  return NextResponse.redirect(origin)
}

Magic Link

const { data, error } = await supabase.auth.signInWithOtp({
  email: 'user@example.com',
})

Auth Middleware

Create src/middleware.ts to protect routes:

import { createServerClient } from '@supabase/ssr'
import { NextResponse, type NextRequest } from 'next/server'

export async function middleware(request: NextRequest) {
  let supabaseResponse = NextResponse.next({ request })
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll()
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) =>
            request.cookies.set(name, value),
          )
          supabaseResponse = NextResponse.next({ request })
          cookiesToSet.forEach(({ name, value, options }) =>
            supabaseResponse.cookies.set(name, value, options),
          )
        },
      },
    },
  )

  const { data: { user } } = await supabase.auth.getUser()

  if (!user && !request.nextUrl.pathname.startsWith('/auth')) {
    const url = request.nextUrl.clone()
    url.pathname = '/auth/login'
    return NextResponse.redirect(url)
  }

  return supabaseResponse
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|auth).*)'],
}

Step 7: Storage Buckets

Create buckets in a migration or via CLI:

insert into storage.buckets (id, name, public)
values ('avatars', 'avatars', false);

Add storage policies:

-- Users can upload their own avatar
create policy "Users upload own avatar"
  on storage.objects for insert
  with check (
    bucket_id = 'avatars'
    and auth.uid()::text = (storage.foldername(name))[1]
  );

-- Users can read their own avatar
create policy "Users read own avatar"
  on storage.objects for select
  using (
    bucket_id = 'avatars'
    and auth.uid()::text = (storage.foldername(name))[1]
  );

Upload pattern in code:

const { data, error } = await supabase.storage
  .from('avatars')
  .upload(`${userId}/avatar.png`, file)

Step 8: TypeScript Type Generation

Generate types from your database schema:

npx supabase gen types typescript --local > src/types/database.ts

Use the generated types with the client:

import { Database } from '@/types/database'

const supabase = createBrowserClient<Database>(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
)

Re-run type generation after every migration.

Step 9: Edge Functions (Optional)

Create an edge function:

npx supabase functions new <function-name>

Deploy:

npx supabase functions deploy <function-name>

Use edge functions for webhooks, scheduled tasks, or complex server-side logic that doesn't fit in Next.js API routes.

Setup Checklist