Everything so far has used the hosted Supabase Cloud dashboard directly. That's fine for learning, but for real projects you want to develop and test against a local copy of Supabase before touching production data. That's what the CLI is for.
Why Local Development Matters
Testing directly against your production database is risky — a bad migration, a wrong delete query, or a broken RLS policy affects real data immediately. The Supabase CLI runs the entire Supabase stack (Postgres, Auth, Storage, Realtime, Edge Functions, and the Studio dashboard) on your own machine using Docker containers. You get an environment that behaves identically to production, isolated from it completely.
Prerequisite: Docker
The local stack runs in Docker containers, so you need a container runtime installed first — Docker Desktop is the standard choice. Make sure it's running before using any CLI command that starts the local stack.
Step 1 — Install the CLI
# As a project dev dependency (recommended) npm install -D supabase
# macOS/Linux via Homebrew brew install supabase/tap/supabase
If you installed it as a project dependency, run every command below as npx supabase <command> instead of just supabase <command>.
Step 2 — Initialize Your Project
From your Next.js project's root folder:
npx supabase init
This creates a supabase/ folder containing config.toml and space for migrations, functions, and seed data. This folder is safe — and expected — to commit to version control. It's the CLI's project scope: most other commands must be run from this same directory.
Step 3 — Start the Local Stack
npx supabase start
This downloads the required Docker images (first run only, takes a few minutes) and boots the full stack locally: Postgres, Auth, Storage, Realtime, and the Data API. At least 7GB of RAM is recommended to run all services comfortably.
Step 4 — Check Your Local Credentials
npx supabase status
This prints your local project's URL, publishable/anon key, secret/service_role key, and — importantly — a local Studio URL (typically http://localhost:54323), which is the same dashboard interface you've been using on the cloud, now running against your local database. Use these local values in a separate .env.local (or a .env.local.development) while developing, instead of your production keys.
Step 5 — Link to Your Hosted Project
Local and hosted (cloud) projects are separate until you explicitly connect them:
npx supabase login npx supabase link
login authenticates the CLI with your Supabase account. link connects your local supabase/ folder to a specific hosted project, which is what lets you push schema changes from local to production later (covered fully in Post 2.4 — Database Migrations).
Step 6 — Stop the Stack When Done
npx supabase stop
This shuts down the Docker containers without deleting your local data (unless you pass --no-backup... which we won't get into yet — default behavior is safe).
The Core CLI Workflow You'll Use Throughout This Course
|
|---|
You don't need to memorize all of these now — this table is a reference point. We'll use migration, db push, and gen types properly once we reach Phase 2 (Database) and Phase 9 (Production), and functions when we reach Phase 7 (Edge Functions).
This closes out Phase 1: Foundations. You now understand what Supabase actually is, its 8 core pillars, the current 2026 platform state, a fully connected Next.js App Router project, and how to develop locally with the CLI.
Next up — Post 2.1: Phase 2 begins — Schema design fundamentals: tables, columns, data types, and constraints in Postgres.
No comments:
Post a Comment