Project setup, CLI and environment variables

Introduction

This post covers creating a Supabase project (cloud or local), installing and using the Supabase CLI, the resulting folder structure, and how to manage environment variables (URL, anon key, service role key) safely. It follows environment-based config and no secrets in repo.

Goal: Have a working project (cloud or local), CLI ready for migrations, and a clear split of dev/staging/prod via env.

Features

Create a project

• Cloud: Sign up at Supabase → New project → choose org, region, DB password. After creation you get: Project URL, anon (public) key, service_role (secret) key.
• Local: Use Supabase CLI (supabase init then supabase start) to run Postgres + Auth + PostgREST in Docker; good for offline dev and no cloud cost.

Supabase CLI

The CLI is used to: link a cloud project, create/apply migrations, generate TypeScript types, run the local stack. Main commands: supabase init, supabase start/stop, supabase db push, supabase migration new/list.

Environment variables

• SUPABASE_URL (or NEXT_PUBLIC_SUPABASE_URL if the client needs it): Project API URL.
• SUPABASE_ANON_KEY: Public key for frontend; restricted by RLS.
• SUPABASE_SERVICE_ROLE_KEY: Secret key, bypasses RLS; backend only, never expose to client or logs.

Convention: each environment (dev, staging, prod) has its own set of variables; secrets come only from env or a secret manager, never from the repo.

Workflow / process

1. Install CLI: npm i -g supabase or Homebrew / Scoop.
2. Create cloud project (if using cloud): Dashboard → New project → store URL and keys in a password manager or sample env (do not commit real keys).
3. Init repo (local workflow): supabase init → creates supabase/ (config.toml, migrations/).
4. Link project (if using cloud): supabase link --project-ref <ref> → enter DB password when prompted; ref from project URL.
5. Run local: supabase start → use the URL and anon key printed in the terminal for your local app.
6. App env: Create .env.local (or equivalent) from .env.example; .env.example lists variable names only, no real values. Example:
   • SUPABASE_URL=
   • SUPABASE_ANON_KEY=
   • SUPABASE_SERVICE_ROLE_KEY= (backend only, optional on client)

Naming: use a consistent prefix (e.g. SUPABASE_*) so it’s easy to audit and to block accidental commits (pre-commit or CI can block files containing service_role).

Sample code

.env.example (do not commit real values)

# Supabase
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

Read env in Node (backend)

function getSupabaseConfig() {
  const url = process.env.SUPABASE_URL;
  const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
  if (!url || !serviceRoleKey) {
    throw new Error('Missing SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY');
  }
  return { url, serviceRoleKey };
}
// Use service role on server only; do not log url/key.

supabase/config.toml (excerpt)

[project]
id = "your-project-ref"
 
[api]
enabled = true
port = 54321

Migrations live in supabase/migrations/; order is by file name (timestamp).

Apply in your architecture

• Environment-based config: Each environment (dev/staging/prod) has its own URL and keys; the app never hardcodes them, only reads from env. Keeps data and permissions separate per env.
• No secrets in repo: Anon key can be public (still limited by RLS); service role key must never go in the repo or logs. Use .env.example and a secret manager/CI variables for real keys.
• Single config source: URL and keys are the “contract” between app and Supabase; consistent variable names help onboarding and audit (e.g. “all SUPABASE_* from env”).

Summary

After this post you have a Supabase project (cloud or local), CLI ready, and env clearly split per environment with no secrets in repo. Next: schema and table design (naming, UUID, migrations).

Next: 03 — Schema and table design

Further reading: Supabase CLI Reference