Getting started

This page covers how to clone the repo, install dependencies, and run any of the apps locally. The full contributor guide is in DEVELOPERS.md at the repo root; this is a condensed, navigation-focused version.

Prerequisites

• Node.js — version is pinned in .nvmrc (currently the Node 22 line; package.json requires node >=22).
• pnpm — the lockfile is pnpm-lock.yaml. The repo uses pnpm >=9 (currently pnpm@10.24 per package.json's packageManager field). npx only-allow pnpm is enforced in preinstall.
• Git, make, and a working C toolchain (for native modules used by libpg-query and friends).
• Docker Desktop if you plan to run Studio against a real Supabase stack via docker compose.

Install

git clone https://github.com/supabase/supabase.git
cd supabase
pnpm install

pnpm install installs every workspace at once. Turborepo handles cross-package builds.

Run an app

Command	What it runs
pnpm dev	Every dev task in parallel (heavy — usually you want a filter).
pnpm dev:studio	Studio dashboard on http://localhost:8082.
pnpm dev:docs	Docs site on http://localhost:3001/docs.
pnpm dev:www	Marketing site on http://localhost:3000.
pnpm dev:design-system	Design-system docs on http://localhost:3003.

Studio expects a backing Supabase stack. The pnpm dev:studio command alone gives you the UI; to talk to a database you have two options:

1. Local CLI: pnpm setup:cli runs supabase start -x studio (skipping the bundled Studio), captures keys into keys.json, and writes a local .env. After that, Studio's pnpm dev will connect to the CLI's services.
2. Self-hosted docker: cd docker && cp .env.example .env && docker compose up, then update apps/studio/.env with the docker Postgres password and service-role key.

Run a build

pnpm build              # build everything (turbo orchestrates)
pnpm build:studio       # only Studio
pnpm build:docs         # only docs
pnpm build:design-system

Output directories: apps/<name>/.next for the Next.js apps, apps/lite-studio/build/ for the Vite app, and dist//build/ for packages.

Tests

Command	What runs
pnpm test:studio	Studio Vitest suite.
pnpm test:studio:watch	Studio Vitest in watch mode.
pnpm test:ui / pnpm test:ui-patterns	Component package tests.
pnpm test:docs	Docs site tests.
pnpm e2e	Playwright e2e suite for Studio (e2e/studio).
pnpm e2e:setup:cli	Boots the local CLI stack and seeds it for e2e.

See how-to-contribute/testing.md for the full test layout.

Lint, typecheck, format

pnpm lint           # turbo run lint across the workspace
pnpm typecheck      # turbo run typecheck (uses --continue)
pnpm test:prettier  # check formatting
pnpm format         # rewrite formatting
pnpm knip           # dead-code/dependency check via knip.jsonc

Studio also has a "ratchet" script (pnpm --filter studio lint:ratchet) that prevents regression on a curated set of ESLint rules — see how-to-contribute/tooling.md.

Self-host stack

Everything needed to run a complete Supabase platform on a single host lives under docker/:

cd docker
cp .env.example .env  # then edit secrets!
docker compose up -d

The dashboard is then reachable on http://localhost:8000. See deployment/index.md for the full bundle and docker/README.md at the repo root for production-hardening notes.

Common gotchas

• pnpm install fails on native modules — make sure your Node version matches .nvmrc. libpg-query and node-pty need a working C toolchain.
• Studio cannot reach Postgres — copy the POSTGRES_PASSWORD and SUPABASE_SERVICE_KEY from your docker .env into apps/studio/.env.
• Stale Turborepo cache — pnpm clean removes node_modules, .next, .turbo, and Turborepo's cache.

Where to look next

• Apps — what each app under apps/ does.
• Packages — what is in each shared workspace.
• Development workflow — branch / PR / review loop.