supabase-local-development

constellos 的头像作者 constellos

当用户请求“在本地启动supabase”、“设置本地supabase”、“运行supabase dev”、“初始化supabase项目”、“配置本地数据库”、“启动本地PostgreSQL”、“使用supabase CLI”、“生成数据库类型”或需要关于本地Supabase开发、Docker设置、环境配置或数据库迁移的指导时,应使用此技能。

📖 中文导读:当用户请求“在本地启动supabase”、“设置本地supabase”、“运行supabase dev”、“初始化supabase项目”、“配置本地数据库”、“启动本地PostgreSQL”、“使用supabase CLI”、“生成数据库类型”或需要关于本地Supabase开发、Docker设置、环境配置或数据库迁移的指导时,应使用此技能。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Supabase Local Development description: This skill should be used when the user asks to "start supabase locally", "set up local supabase", "run supabase dev", "initialize supabase project", "configure local database", "start local postgres", "use supabase CLI", "generate database types", or needs guidance on local Supabase development, Docker setup, environment configuration, or database migrations. version: 0.1.0

Supabase Local Development

Overview

Supabase Local Development provides a complete local Postgres database with all Supabase services (Auth, Storage, Edge Functions, Realtime) running in Docker containers. This enables offline development, faster iteration, and safe database migrations before deploying to production.

Key benefits:

  • Full Supabase stack running locally
  • Faster development without network latency
  • Safe migration testing before production
  • Automatic TypeScript type generation
  • Environment variable management

Skill-scoped Context

Official Documentation:

Prerequisites

Docker Runtime

Supabase local development requires a Docker-compatible container runtime:

  • Docker Desktop (macOS, Windows, Linux)
  • Rancher Desktop (macOS, Windows, Linux)
  • OrbStack (macOS) - Recommended for Apple Silicon
  • Podman (macOS, Windows, Linux)

Verify Docker is running:

docker info

Supabase CLI

Install via npm (recommended for Next.js projects):

npm install -g supabase

Or via Homebrew (macOS):

brew install supabase/tap/supabase

Verify installation:

supabase --version

Workflow

Step 1: Initialize Supabase Project

supabase init

This creates a supabase/ directory with:

  • config.toml - Local configuration
  • seed.sql - Optional seed data
  • migrations/ - Database migrations

Step 2: Start Local Services

supabase start

First run downloads Docker images (~2GB). Subsequent starts are faster.

Services started:

Service Local URL Purpose
API http://127.0.0.1:54321 REST/GraphQL API
Studio http://127.0.0.1:54323 Database UI
Inbucket http://127.0.0.1:54324 Email testing
Database postgresql://127.0.0.1:54322 Direct Postgres

Step 3: Get Environment Variables

supabase status -o env

Output:

SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...
SUPABASE_DB_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

Step 4: Configure Next.js Environment

Add to .env.local:

# Supabase Local Development
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...

Note: NEXT_PUBLIC_ prefix exposes variables to the browser.

Step 5: Generate TypeScript Types

supabase gen types typescript --local > lib/supabase/database.types.ts

Regenerate after schema changes.

Environment Variables

Client-Side (Browser)

Prefix with NEXT_PUBLIC_:

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

Server-Side Only

No prefix required:

SUPABASE_SERVICE_ROLE_KEY=eyJ...
SUPABASE_DB_URL=postgresql://...

Environment File Detection

Framework File Priority
Next.js .env.local 1st
Next.js .env.development.local 2nd
Generic .env 3rd
Cloudflare Workers dev.vars Special

Database Migrations

Create Migration from Local Changes

supabase db diff -f migration_name

Apply Migrations Locally

supabase db reset

Push to Remote Database

supabase db push
supabase link --project-ref YOUR_PROJECT_REF

Type Generation

From Local Database

supabase gen types typescript --local > lib/supabase/database.types.ts

From Remote Database

supabase gen types typescript --project-id YOUR_PROJECT_ID > lib/supabase/database.types.ts

Usage in Code

import { createClient } from "@supabase/supabase-js";
import type { Database } from "@/lib/supabase/database.types";

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

Common Commands Reference

Command Purpose
supabase init Initialize new project
supabase start Start local services
supabase stop Stop local services
supabase status Show service status
supabase status -o env Output as environment variables
supabase db reset Reset database and apply migrations
supabase db diff -f name Create migration from changes
supabase db push Push migrations to remote
supabase gen types typescript --local Generate types from local
supabase link --project-ref REF Link to remote project

Troubleshooting

Docker Not Running

# macOS - Start Docker Desktop
open -a Docker

# Linux - Start Docker daemon
sudo systemctl start docker

Port Conflicts

If ports are in use:

supabase stop --no-backup
supabase start

Or configure different ports in supabase/config.toml.

Reset Everything

supabase stop --no-backup
supabase start
supabase db reset

Best Practices

DO:

  • Always use supabase db diff for migrations
  • Regenerate types after schema changes
  • Use .env.local for local credentials (gitignored)
  • Test migrations locally before pushing to production

DON'T:

  • Commit local Supabase credentials
  • Modify production database directly
  • Skip local testing for migrations
  • Use service role key in client-side code