supabase-local-dev-loop

name	supabase-local-dev-loop
description	Configure Supabase local development with the CLI, Docker, and migration workflow. Use when initializing a Supabase project locally, starting the local stack, writing migrations, seeding data, or iterating on schema changes. Trigger with phrases like "supabase local dev", "supabase start", "supabase init", "supabase db reset", "supabase local setup".
allowed-tools	Read, Write, Edit, Bash(npx:*), Bash(supabase:*), Bash(docker:*), Bash(curl:*), Grep
version	1.53.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","supabase","local-development","docker","postgres"]
compatibility	Designed for Claude Code

Supabase Local Dev Loop

Overview

Run the full Supabase stack locally — Postgres, Auth, Storage, Realtime, Edge Functions, and Studio — using Docker and the Supabase CLI. Local development mirrors production APIs exactly, enabling offline work, fast iteration, and repeatable migration workflows. Schema changes flow through supabase db diff to generate migrations, and supabase db reset replays them cleanly.

Prerequisites

• Docker Desktop installed and running (required for all local services)
• Node.js 18+ (for npx supabase commands)
• No global install needed — all commands use npx supabase

Instructions

Step 1: Initialize Project and Start Local Stack

# Initialize Supabase in your project root
npx supabase init

This creates a supabase/ directory:

supabase/
├── config.toml          # Local stack configuration (ports, auth settings)
├── migrations/          # SQL migration files (version-controlled)
└── seed.sql             # Seed data (runs after migrations on db reset)

Start the local stack (first run pulls Docker images — takes a few minutes):

npx supabase start

The CLI prints all local endpoints and keys:

API URL:          http://localhost:54321
GraphQL URL:      http://localhost:54321/graphql/v1
S3 Storage URL:   http://localhost:54321/storage/v1/s3
DB URL:           postgresql://postgres:postgres@localhost:54322/postgres
Studio URL:       http://localhost:54323
Inbucket URL:     http://localhost:54324
anon key:         eyJhbGciOiJI...
service_role key: eyJhbGciOiJI...

Create .env.local from these values (git-ignored):

# .env.local
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=<anon-key-from-supabase-start>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key-from-supabase-start>
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

Verify the stack is running:

npx supabase status

Step 2: Create Migrations and Seed Data

Create a migration file with a descriptive name:

npx supabase migration new create_profiles
# Creates: supabase/migrations/<timestamp>_create_profiles.sql

Write the migration SQL: