Supabase Setup

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