Skip to content
AnglinAI Docs

Prompt: Set Up Local Supabase Dev Environment

Copy and paste this entire prompt to Claude Code when you’re ready to implement Option B.

Context

We have two Next.js apps that use Supabase for authentication and data:

  1. accessible-org-chart — ~/Projects/accessible-org-chart/

    • Frontend: Next.js static export → Cloudflare Pages (apps/web/)
    • API: Hono on Node.js in Docker (workers/api/)
    • Auth: Supabase magic-link + Google OAuth
    • Current dev workaround: DevAutoLogin component reads NEXT_PUBLIC_DEV_AUTO_LOGIN_* from .env.local and calls supabase.auth.signInWithPassword on mount (Option A, already implemented)

  2. accessible-pdf-converter — ~/Projects/accessible-pdf-converter/

    • Frontend: Next.js static export → Cloudflare Pages (apps/web/)
    • API: Hono Cloudflare Workers (workers/api/)
    • Auth: Supabase magic-link + Google OAuth, multi-tenant
    • Same DevAutoLogin Option A already implemented

Both projects already have:

  • supabase/migrations/ directories with the full schema history
  • apps/web/.env.local.example documenting required env vars
  • apps/web/.env.production with live Supabase credentials (DO NOT MODIFY)
  • Docker Compose for the org-chart API (docker-compose.yml at repo root)

Goal

Replace the Option A env-var auto-login with a fully isolated local Supabase stack so that:

  • Local dev uses a completely separate database (no risk to production data)
  • Schema migrations can be tested before deploying to production
  • Test data can be seeded and reset freely
  • The DevAutoLogin component still works, just pointed at localhost Supabase

What to implement

1. Supabase CLI setup

  • Verify supabase CLI is installed (supabase --version); install via Homebrew if not
  • Run supabase init in each project root if a supabase/ directory doesn’t already exist (it does — just verify)
  • The local Supabase stack requires Docker Desktop to be running

2. supabase/config.toml review

  • Review and update supabase/config.toml in each project:
    • project_id should match the project name (e.g. accessible-org-chart)
    • Auth providers should match what’s in production: email (magic link + password), google
    • For local dev, email.enable_confirmations = false so we don’t need to click email links
    • Disable all external SMTP (use Supabase’s built-in Inbucket for email capture)

3. Start the local stack

Terminal window
# In each project root:
supabase start

This starts: Postgres (port 54322), Auth (port 54321), API (port 54321), Studio (port 54323), Inbucket email capture (port 54324).

After starting, supabase status outputs the local API URL, anon key, and service_role key.

4. .env.local updates

Update apps/web/.env.local in each project to point at local Supabase:

# Local Supabase (from `supabase status`)
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<local anon key from supabase status>


# Dev auto-login (unchanged — still used by DevAutoLogin component)
[email protected]
NEXT_PUBLIC_DEV_AUTO_LOGIN_PASSWORD=<same password as before>

For org-chart API (workers/api/.env), add:

SUPABASE_URL=http://localhost:54321
SUPABASE_SERVICE_ROLE_KEY=<local service_role key from supabase status>
SUPABASE_JWT_SECRET=<local JWT secret from supabase status>

5. Run migrations locally

Terminal window
supabase db reset  # applies all migrations in supabase/migrations/ from scratch

Verify the schema matches production by inspecting Supabase Studio at http://localhost:54323.

6. Seed script

Create supabase/seed.sql for each project containing:

accessible-org-chart seed:

  • A test user [email protected] created via auth.users insert (use Supabase’s crypt() for password)
    • Alternatively, use supabase auth CLI: supabase auth admin create-user --email [email protected] --password <password>
  • 2–3 sample org charts owned by the test user
  • Sample org chart people/relationships so the dashboard has data to display
  • A test admin user [email protected]

accessible-pdf-converter seed:

  • A test user [email protected] with email/password auth
  • A default tenant record pointing to localhost
  • 2–3 sample conversion jobs in various statuses (pending, completed, failed)
  • A test admin user

The seed runs automatically on supabase db reset. Add a npm run db:reset script to each project’s package.json:

"db:reset": "supabase db reset"

7. Docker Compose integration (org-chart only)

The org-chart API runs in Docker. Update docker-compose.yml to add a dev profile that points the API at local Supabase instead of production. The production Docker Compose should remain unchanged.

Add a docker-compose.dev.yml override file:

# Usage: docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
services:
  api:
    environment:
      SUPABASE_URL: http://host.docker.internal:54321
      SUPABASE_SERVICE_ROLE_KEY: <local service_role key>
      SUPABASE_JWT_SECRET: <local JWT secret>

8. Update .env.local.example

Update apps/web/.env.local.example in each project to document the local Supabase values and how to get them via supabase status.

9. npm run dev convenience script (optional)

Consider adding a root-level dev script in each project’s package.json that:

  1. Checks if Supabase is running (supabase status)
  2. Starts it if not (supabase start)
  3. Runs next dev

10. Document in docs/admin/local-dev.md

Create a step-by-step runbook in each project at docs/admin/local-dev.md covering:

  • Prerequisites (Docker Desktop, Supabase CLI, Node.js)
  • First-time setup steps (clone → .env.local → supabase start → supabase db reset → npm run dev)
  • Day-to-day workflow
  • How to reset to a clean state (supabase db reset)
  • How to create and apply a new migration (supabase migration new <name> → edit → supabase db reset)
  • How to push a migration to production (supabase db push)

Constraints

  • Do NOT modify apps/web/.env.production in either project
  • Do NOT modify the production Docker Compose (docker-compose.yml) in a way that breaks production deployment
  • The DevAutoLogin component already exists — do NOT rewrite it, just ensure the local Supabase instance accepts signInWithPassword for the dev user
  • All new files must follow existing code style (TypeScript strict, camelCase, etc.)
  • The supabase/migrations/ directories must not be modified — run them as-is against local Supabase

Reference files to read first

Before starting, read these files in each project to understand the current state:

  • supabase/config.toml — Supabase project configuration
  • supabase/migrations/ — all migration files (understand the schema)
  • apps/web/.env.local.example — env var documentation
  • apps/web/src/lib/supabase.ts — Supabase client setup
  • workers/api/.env.example (if it exists) — API env var documentation
  • docker-compose.yml (org-chart only) — current Docker setup