Antigravity × Supabase Complete Production Guide — Mastering Auth, RLS, Edge Functions, and Realtime for Real-World Apps

# Install Supabase CLI
npm install supabase --save-dev
 
# Initialize the project
npx supabase init
 
# Start local Supabase (requires Docker)
npx supabase start

# Project Rules
 
## Tech Stack
- Next.js 15+ App Router
- Supabase (PostgreSQL + Auth + Storage + Realtime)
- TypeScript (strict mode)
- Tailwind CSS
 
## Supabase Conventions
- Table names: snake_case (plural)
- Column names: snake_case
- RLS must be enabled on all tables
- service_role key is server-side only
 
## Security Rules
- Client-side code uses anon key only
- All user data access must be controlled by RLS
- service_role is only used inside Edge Functions

// lib/supabase/client.ts — for client components
import { createBrowserClient } from '@supabase/ssr'
import type { Database } from '@/types/supabase'
 
export function createClient() {
  return createBrowserClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}
 
// lib/supabase/server.ts — for server components and Server Actions
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 when called from Server Components
          }
        },
      },
    }
  )
}

// app/auth/callback/route.ts — OAuth callback handler
import { createClient } from '@/lib/supabase/server'
import { NextResponse } from 'next/server'
 
export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url)
  const code = searchParams.get('code')
  const next = searchParams.get('next') ?? '/'
 
  if (code) {
    const supabase = await createClient()
    const { error } = await supabase.auth.exchangeCodeForSession(code)
    if (!error) {
      return NextResponse.redirect(`${origin}${next}`)
    }
  }
 
  // On error, redirect to error page
  return NextResponse.redirect(`${origin}/auth/error`)
}

// middleware.ts
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)
          )
        },
      },
    }
  )
 
  // Refresh session (important: always call this)
  const {
    data: { user },
  } = await supabase.auth.getUser()
 
  // Redirect unauthenticated users away from protected routes
  if (!user && request.nextUrl.pathname.startsWith('/dashboard')) {
    const url = request.nextUrl.clone()
    url.pathname = '/login'
    return NextResponse.redirect(url)
  }
 
  return supabaseResponse
}
 
export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
}

-- supabase/migrations/20260404_create_profiles.sql
 
-- Create profiles table
create table public.profiles (
  id uuid references auth.users on delete cascade not null primary key,
  username text unique,
  full_name text,
  avatar_url text,
  subscription_tier text default 'free' check (subscription_tier in ('free', 'pro', 'premium')),
  created_at timestamptz default now() not null,
  updated_at timestamptz default now() not null
);
 
-- Enable RLS (required)
alter table public.profiles enable row level security;
 
-- Policy: users can only view their own profile
create policy "Users can view own profile"
  on public.profiles
  for select
  using (auth.uid() = id);
 
-- Policy: users can only update their own profile
create policy "Users can update own profile"
  on public.profiles
  for update
  using (auth.uid() = id);
 
-- Trigger to automatically create a profile on user signup
create or replace function public.handle_new_user()
returns trigger as $$
begin
  insert into public.profiles (id, full_name, avatar_url)
  values (
    new.id,
    new.raw_user_meta_data->>'full_name',
    new.raw_user_meta_data->>'avatar_url'
  );
  return new;
end;
$$ language plpgsql security definer;
 
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_user();

-- supabase/migrations/20260404_create_teams.sql
 
-- Teams table
create table public.teams (
  id uuid default gen_random_uuid() primary key,
  name text not null,
  owner_id uuid references auth.users not null,
  plan text default 'free' check (plan in ('free', 'pro', 'enterprise')),
  created_at timestamptz default now() not null
);
 
-- Team members junction table
create table public.team_members (
  team_id uuid references public.teams on delete cascade not null,
  user_id uuid references auth.users on delete cascade not null,
  role text default 'member' check (role in ('owner', 'admin', 'member')),
  joined_at timestamptz default now() not null,
  primary key (team_id, user_id)
);
 
-- Projects table (scoped to a team)
create table public.projects (
  id uuid default gen_random_uuid() primary key,
  team_id uuid references public.teams on delete cascade not null,
  name text not null,
  description text,
  status text default 'active' check (status in ('active', 'archived')),
  created_at timestamptz default now() not null,
  updated_at timestamptz default now() not null
);
 
-- Enable RLS
alter table public.teams enable row level security;
alter table public.team_members enable row level security;
alter table public.projects enable row level security;
 
-- Helper: check if current user is a team member
create or replace function public.is_team_member(team_id uuid)
returns boolean as $$
  select exists (
    select 1 from public.team_members
    where team_members.team_id = $1
    and team_members.user_id = auth.uid()
  )
$$ language sql security definer stable;
 
-- Helper: check if current user is a team admin
create or replace function public.is_team_admin(team_id uuid)
returns boolean as $$
  select exists (
    select 1 from public.team_members
    where team_members.team_id = $1
    and team_members.user_id = auth.uid()
    and team_members.role in ('owner', 'admin')
  )
$$ language sql security definer stable;
 
-- Teams policies
create policy "Team members can view their teams"
  on public.teams for select
  using (public.is_team_member(id));
 
create policy "Team owners can update team"
  on public.teams for update
  using (owner_id = auth.uid());
 
-- Projects policies
create policy "Team members can view projects"
  on public.projects for select
  using (public.is_team_member(team_id));
 
create policy "Team admins can create projects"
  on public.projects for insert
  with check (public.is_team_admin(team_id));
 
create policy "Team admins can update projects"
  on public.projects for update
  using (public.is_team_admin(team_id));

// lib/supabase/queries/projects.ts
import { createClient } from '@/lib/supabase/server'
import type { Database } from '@/types/supabase'
 
type Project = Database['public']['Tables']['projects']['Row']
 
export async function getProjectsByTeam(teamId: string): Promise<Project[]> {
  const supabase = await createClient()
 
  const { data, error } = await supabase
    .from('projects')
    .select(`
      *,
      team:teams(name, plan)
    `)
    .eq('team_id', teamId)
    .eq('status', 'active')
    .order('created_at', { ascending: false })
 
  if (error) {
    console.error('Failed to fetch projects:', error)
    throw new Error(error.message)
  }
 
  // RLS automatically ensures only authorized projects are returned
  return data
}

// supabase/functions/stripe-webhook/index.ts
import Stripe from 'npm:stripe@14'
import { createClient } from 'npm:@supabase/supabase-js@2'
 
const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!, {
  httpClient: Stripe.createFetchHttpClient(),
})
 
const supabase = createClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')! // service_role is safe inside Edge Functions
)
 
Deno.serve(async (req) => {
  const signature = req.headers.get('stripe-signature')!
  const body = await req.text()
 
  let event: Stripe.Event
  try {
    event = await stripe.webhooks.constructEventAsync(
      body,
      signature,
      Deno.env.get('STRIPE_WEBHOOK_SECRET')!
    )
  } catch (err) {
    console.error('Webhook signature verification failed:', err)
    return new Response('Invalid signature', { status: 400 })
  }
 
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session
    const userId = session.metadata?.user_id
    const plan = session.metadata?.plan
 
    if (userId && plan) {
      const { error } = await supabase
        .from('profiles')
        .update({
          subscription_tier: plan,
          updated_at: new Date().toISOString(),
        })
        .eq('id', userId)
 
      if (error) {
        console.error('Failed to update subscription:', error)
        return new Response('Database error', { status: 500 })
      }
    }
  }
 
  if (event.type === 'customer.subscription.deleted') {
    const subscription = event.data.object as Stripe.Subscription
    const userId = subscription.metadata?.user_id
 
    if (userId) {
      await supabase
        .from('profiles')
        .update({ subscription_tier: 'free', updated_at: new Date().toISOString() })
        .eq('id', userId)
    }
  }
 
  return new Response(JSON.stringify({ received: true }), {
    headers: { 'Content-Type': 'application/json' },
  })
})

# Serve locally for development
npx supabase functions serve stripe-webhook --env-file .env.local
 
# Deploy to production
npx supabase functions deploy stripe-webhook --no-verify-jwt
 
# Set secrets
npx supabase secrets set STRIPE_SECRET_KEY=sk_live_...
npx supabase secrets set STRIPE_WEBHOOK_SECRET=whsec_...

// hooks/useRealtimeChat.ts
'use client'
 
import { useState, useEffect, useCallback } from 'react'
import { createClient } from '@/lib/supabase/client'
import type { RealtimeChannel } from '@supabase/supabase-js'
 
interface Message {
  id: string
  content: string
  role: 'user' | 'assistant'
  created_at: string
}
 
export function useRealtimeChat(conversationId: string) {
  const [messages, setMessages] = useState<Message[]>([])
  const [isStreaming, setIsStreaming] = useState(false)
  const supabase = createClient()
 
  useEffect(() => {
    // Fetch existing messages
    const fetchMessages = async () => {
      const { data } = await supabase
        .from('messages')
        .select('*')
        .eq('conversation_id', conversationId)
        .order('created_at', { ascending: true })
      if (data) setMessages(data)
    }
    fetchMessages()
 
    // Set up Realtime subscription
    const channel: RealtimeChannel = supabase
      .channel(`conversation:${conversationId}`)
      .on(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'messages',
          filter: `conversation_id=eq.${conversationId}`,
        },
        (payload) => {
          const newMessage = payload.new as Message
          setMessages((prev) => [...prev, newMessage])
          if (newMessage.role === 'assistant') {
            setIsStreaming(false)
          }
        }
      )
      .subscribe()
 
    return () => {
      supabase.removeChannel(channel)
    }
  }, [conversationId, supabase])
 
  const sendMessage = useCallback(async (content: string) => {
    setIsStreaming(true)
 
    // Save user message to DB
    await supabase.from('messages').insert({
      conversation_id: conversationId,
      content,
      role: 'user',
    })
 
    // Invoke Edge Function to generate AI response
    await supabase.functions.invoke('ai-chat', {
      body: { conversation_id: conversationId, message: content },
    })
  }, [conversationId, supabase])
 
  return { messages, isStreaming, sendMessage }
}

// hooks/usePresence.ts
'use client'
 
import { useState, useEffect } from 'react'
import { createClient } from '@/lib/supabase/client'
 
interface UserPresence {
  user_id: string
  username: string
  online_at: string
}
 
export function usePresence(roomId: string, currentUser: { id: string; name: string }) {
  const [onlineUsers, setOnlineUsers] = useState<UserPresence[]>([])
  const supabase = createClient()
 
  useEffect(() => {
    const channel = supabase.channel(`presence:${roomId}`, {
      config: {
        presence: {
          key: currentUser.id,
        },
      },
    })
 
    channel
      .on('presence', { event: 'sync' }, () => {
        const state = channel.presenceState<UserPresence>()
        const users = Object.values(state).flat()
        setOnlineUsers(users)
      })
      .subscribe(async (status) => {
        if (status === 'SUBSCRIBED') {
          await channel.track({
            user_id: currentUser.id,
            username: currentUser.name,
            online_at: new Date().toISOString(),
          })
        }
      })
 
    return () => {
      supabase.removeChannel(channel)
    }
  }, [roomId, currentUser, supabase])
 
  return { onlineUsers }
}

// app/actions/upload.ts
'use server'
 
import { createClient } from '@/lib/supabase/server'
import { revalidatePath } from 'next/cache'
 
export async function uploadFile(formData: FormData) {
  const supabase = await createClient()
  const {
    data: { user },
  } = await supabase.auth.getUser()
 
  if (!user) {
    return { error: 'Authentication required' }
  }
 
  const file = formData.get('file') as File
  if (!file) {
    return { error: 'No file selected' }
  }
 
  // File size limit (5MB)
  if (file.size > 5 * 1024 * 1024) {
    return { error: 'File size must be 5MB or less' }
  }
 
  // Store in a per-user directory
  const fileName = `${Date.now()}-${file.name.replace(/[^a-zA-Z0-9.-]/g, '_')}`
  const filePath = `${user.id}/${fileName}`
 
  const { error } = await supabase.storage
    .from('user-uploads')
    .upload(filePath, file, {
      cacheControl: '3600',
      upsert: false,
    })
 
  if (error) {
    console.error('Upload error:', error)
    return { error: 'Upload failed' }
  }
 
  // Save file metadata to DB
  await supabase.from('files').insert({
    user_id: user.id,
    file_path: filePath,
    file_name: file.name,
    file_size: file.size,
    mime_type: file.type,
  })
 
  revalidatePath('/dashboard/files')
  return { success: true, path: filePath }
}
 
export async function getSignedUrl(filePath: string) {
  const supabase = await createClient()
 
  // Signed URL valid for 1 hour
  const { data, error } = await supabase.storage
    .from('user-uploads')
    .createSignedUrl(filePath, 3600)
 
  if (error) return { error: error.message }
  return { url: data.signedUrl }
}

-- Users can only upload to their own directory
create policy "Users can upload own files"
  on storage.objects for insert
  to authenticated
  with check (
    bucket_id = 'user-uploads'
    and (storage.foldername(name))[1] = auth.uid()::text
  );
 
-- Users can only view their own files
create policy "Users can view own files"
  on storage.objects for select
  to authenticated
  using (
    bucket_id = 'user-uploads'
    and (storage.foldername(name))[1] = auth.uid()::text
  );
 
-- Users can only delete their own files
create policy "Users can delete own files"
  on storage.objects for delete
  to authenticated
  using (
    bucket_id = 'user-uploads'
    and (storage.foldername(name))[1] = auth.uid()::text
  );

# Generate types from local environment
npx supabase gen types typescript --local > types/supabase.ts
 
# Generate types from production (requires project ID)
npx supabase gen types typescript \
  --project-id YOUR_PROJECT_ID \
  --schema public > types/supabase.ts

import type { Database } from '@/types/supabase'
 
type Tables = Database['public']['Tables']
type Profile = Tables['profiles']['Row']
type ProfileUpdate = Tables['profiles']['Update']
 
// ✅ Type-checked at compile time
const update: ProfileUpdate = {
  full_name: 'New Name',
  updated_at: new Date().toISOString(),
}
 
// ❌ Non-existent columns cause compile errors
// const invalid: ProfileUpdate = { nonexistent_field: 'value' }

{
  "scripts": {
    "db:types": "supabase gen types typescript --local > types/supabase.ts",
    "db:migrate": "supabase db push",
    "db:reset": "supabase db reset",
    "db:seed": "npx supabase db seed"
  }
}

# .env.local (local development)
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
 
# For Vercel / Cloudflare Workers: set via dashboard or CLI

-- Add indexes for frequently queried columns
create index idx_messages_conversation_id
  on public.messages (conversation_id, created_at desc);
 
create index idx_projects_team_id
  on public.projects (team_id, status, created_at desc);
 
-- Find slow queries with pg_stat_statements
select query, mean_exec_time, calls
from pg_stat_statements
order by mean_exec_time desc
limit 10;

// lib/supabase/logger.ts
export async function logEvent(
  event: string,
  metadata: Record<string, unknown>
) {
  const supabase = await createClient()
  await supabase.from('audit_logs').insert({
    event,
    metadata,
    created_at: new Date().toISOString(),
  })
}

# .github/workflows/deploy.yml
name: Deploy to Production
 
on:
  push:
    branches: [main]
 
jobs:
  migrate-and-deploy:
    runs-on: ubuntu-latest
    env:
      SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
      SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}
      PROJECT_ID: ${{ secrets.SUPABASE_PROJECT_ID }}
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Supabase CLI
        uses: supabase/setup-cli@v1
        with:
          version: latest
 
      - name: Link Supabase project
        run: supabase link --project-ref $PROJECT_ID
 
      - name: Run database migrations
        run: supabase db push
 
      - name: Deploy Edge Functions
        run: supabase functions deploy --no-verify-jwt
 
      - name: Verify deployment
        run: |
          curl -f https://your-project.supabase.co/rest/v1/ \
            -H "apikey: ${{ secrets.SUPABASE_ANON_KEY }}" \
            || exit 1

// tests/setup.ts
import { execSync } from 'child_process'
import { createClient } from '@supabase/supabase-js'
 
const SUPABASE_URL = 'http://127.0.0.1:54321'
const SUPABASE_SERVICE_ROLE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY!
 
export const testClient = createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY)
 
export async function resetDatabase() {
  // Reset to a clean state before each test suite
  execSync('npx supabase db reset --local', { stdio: 'inherit' })
}
 
export async function seedTestData() {
  // Insert known test data
  const { data: user } = await testClient.auth.admin.createUser({
    email: 'test@example.com',
    password: 'testpassword123',
    email_confirm: true,
  })
 
  if (user.user) {
    await testClient.from('profiles').insert({
      id: user.user.id,
      username: 'testuser',
      full_name: 'Test User',
    })
  }
 
  return { userId: user.user?.id }
}

// tests/projects.test.ts
import { describe, it, expect, beforeAll } from 'vitest'
import { testClient, seedTestData } from './setup'
 
describe('Projects API', () => {
  let userId: string
 
  beforeAll(async () => {
    const seed = await seedTestData()
    userId = seed.userId!
  })
 
  it('should return only projects for the authenticated user', async () => {
    // Create a team and project for the test user
    const { data: team } = await testClient
      .from('teams')
      .insert({ name: 'Test Team', owner_id: userId })
      .select()
      .single()
 
    await testClient.from('projects').insert({
      team_id: team!.id,
      name: 'Test Project',
    })
 
    // Sign in as the test user
    const { data: session } = await testClient.auth.signInWithPassword({
      email: 'test@example.com',
      password: 'testpassword123',
    })
 
    // Create a client as the authenticated user (respects RLS)
    const userClient = createClient(SUPABASE_URL, process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, {
      global: {
        headers: { Authorization: `Bearer ${session.session?.access_token}` },
      },
    })
 
    const { data: projects } = await userClient.from('projects').select('*')
 
    // RLS should ensure only this user's projects are returned
    expect(projects).toHaveLength(1)
    expect(projects![0].name).toBe('Test Project')
  })
})