Skip to main content

​
Supabase Local Development

This guide will help you set up and work with Supabase in your local development environment.

​
Prerequisites

Before getting started, ensure you have the following installed:

​
Quick Setup

The monorepo includes a setup script to quickly get Supabase running locally: 
# Run the automated setup script
pnpm supabase:setup
This script will:
  1. Check for prerequisites
  2. Configure your environment variables
  3. Start Supabase locally
  4. Optionally reset and seed the database

​
Manual Setup

If you prefer to set up Supabase manually, follow these steps:
1

Install the Supabase CLI

# Install the Supabase CLI globally
npm install -g supabase
2

Configure Environment Variables

Create or update your .env.local file in the root of the repo with these variables:
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU
These are the default keys for local Supabase development.
3

Start Supabase

# Navigate to the Supabase directory
cd infra/supabase

# Start Supabase
supabase start
This will start the Supabase services in Docker containers.
4

Apply Migrations

# Reset the database and apply all migrations
supabase db reset
This will apply all migrations in the migrations directory.

​
Accessing Supabase Studio

Once Supabase is running, you can access the Supabase Studio at: 
http://localhost:54323
This provides a web interface for:
  • Browsing and editing your database tables
  • Managing authentication settings
  • Configuring storage buckets
  • Testing edge functions
  • Running SQL queries
  • Viewing logs
Supabase Studio Interface

​
Common Tasks

​
Managing the Database

You can view and edit data directly in the Supabase Studio:
  1. Open Supabase Studio at http://localhost:54323
  2. Click on “Table Editor” in the sidebar
  3. Select a table to view or edit its data
For more advanced operations, you can use the SQL Editor in Supabase Studio.
When making schema changes:
# Create a new migration file
cd infra/supabase
supabase migration new add_new_feature

# Edit the generated file in migrations/[timestamp]_add_new_feature.sql
# Then apply the migration
supabase db reset
Alternatively, you can use the schema-first approach:
  1. Update or create schema files in /data/schemas/
  2. Generate a migration from the differences:
cd infra/supabase
supabase db diff --schema public --file add_new_feature
To reset your database to a clean state:
# From the root of the repository
pnpm supabase:reset

# Or manually
cd infra/supabase
supabase db reset
This will apply all migrations in sequence to rebuild the database.

​
Working with Authentication

You can create test users through the Supabase Studio:
  1. Open Supabase Studio at http://localhost:54323
  2. Go to “Authentication” → “Users”
  3. Click “Add User” and enter the user details
Or through code:
import { getSupabaseClient } from '@repo/supabase-client';

const supabase = getSupabaseClient();
const { data, error } = await supabase.auth.signUp({
  email: '[email protected]',
  password: 'password123'
});
To test auth flows in your application:
  1. Create a test user as described above
  2. Use the user credentials to sign in
  3. Auth state should persist between page reloads
For OAuth providers, you’ll need to configure them in Supabase Studio under “Authentication” → “Providers”.

​
Working with Storage

Storage buckets can be created through the Supabase Studio:
  1. Open Supabase Studio at http://localhost:54323
  2. Go to “Storage”
  3. Click “New Bucket” and enter a name
  4. Configure public/private access as needed
You can upload files through the Supabase Studio or via code:
import { getSupabaseClient } from '@repo/supabase-client';

const supabase = getSupabaseClient();

// Upload a file
const { data, error } = await supabase.storage
  .from('bucket-name')
  .upload('file-path.jpg', fileData);
  
// Get a public URL
const { data } = supabase.storage
  .from('bucket-name')
  .getPublicUrl('file-path.jpg');

​
Common Issues and Solutions

​
Docker Not Running

If you see errors about Docker not running, make sure Docker Desktop is started before running Supabase commands.

​
Port Conflicts

If Supabase fails to start due to port conflicts, check for other services using ports 54321-54325 and stop them.

​
Database Reset Errors

If database reset fails, try stopping and restarting Supabase:

supabase stop && supabase start

​
Auth Not Working

If authentication isn’t working, check that your environment variables are correctly set in both the .env.local file and your application.

​
Best Practices

Use Migrations

Always use migrations for schema changes to keep development and production in sync

Schema First

Define schemas in the /data/schemas/ directory first, then generate migrations

Local Only

Never connect to production databases from your local development environment

RLS Policies

Always implement Row Level Security (RLS) policies for tables

Types First

Keep TypeScript models in sync with database schema changes

Test Data Reset

Regularly reset your local database to ensure your migrations work correctly

​
Next Steps

Now that you have Supabase running locally, you can: If you encounter any issues with the local development setup, please reach out to the development team.