| name | supabase-multi-env-setup |
| description | Configure Supabase across development, staging, and production with separate projects,
environment-specific secrets, and safe migration promotion.
Use when setting up multi-environment deployments, isolating dev from prod data,
configuring per-environment Supabase projects, or promoting migrations through environments.
Trigger with "supabase environments", "supabase staging", "supabase dev prod",
"supabase multi-project", "supabase env config", "database branching".
|
| allowed-tools | Read, Write, Edit, Bash(npx supabase:*), Bash(supabase:*), Bash(vercel:*) |
| version | 1.53.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","supabase","deployment","environments","multi-env","devops"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Supabase Multi-Environment Setup
Overview
Production Supabase deployments require a separate project per environment — each with its
own URL, API keys, database, and RLS policies. This skill configures a three-tier
architecture (local dev, staging, production) with safe migration promotion via
supabase db push, environment-aware createClient initialization, database branching
for preview deployments, and CI/CD that prevents accidental cross-environment operations.
When to use: setting up a new project with multiple environments, migrating from a
single-project setup, adding staging to an existing dev/prod split, or configuring preview
environments with database branching.
Prerequisites
- Three separate Supabase projects created at supabase.com/dashboard (dev, staging, production)
- Supabase CLI installed:
npm install -g supabase or npx supabase --version
@supabase/supabase-js v2+ installed in your project- Node.js 18+ with a framework that supports
.env files (Next.js, Nuxt, SvelteKit, etc.)
- A secret management solution for CI (GitHub Actions Secrets, Vercel env vars, etc.)
Instructions
The workflow is three steps. Each step below gives the shape and the one command that
matters; the full implementation walkthrough carries the
complete env files, TypeScript client factory, RLS policies, CI/CD workflow, and seed data
verbatim.
Step 1: Environment Files and Project Layout
Keep one Supabase CLI project with shared migrations and one .env.* file per
environment. Each file points at a different Supabase project; only .env.local is safe to
commit.
supabase/migrations/ # shared schema — every env applies the same migrations
.env.local # supabase start defaults (safe to commit)
.env.staging # staging project creds (gitignored)
.env.production # production project creds (gitignored — NEVER commit)
The CLI links one project at a time. Before any db push or functions deploy,
re-link to the target:
npx supabase link --project-ref <target-ref>
See the implementation walkthrough (Step 1)
for full .env.* contents, the .gitignore block, and the local-port reference.
