Development workflow

The day-to-day loop for working in this repo. Most engineers spend their time in apps/studio and apps/docs; the steps below assume that.

1. Set up once

git clone https://github.com/supabase/supabase.git
cd supabase
nvm use            # picks up .nvmrc
pnpm install

pnpm install walks the entire workspace (apps/*, packages/*, blocks/*, e2e/*) declared in pnpm-workspace.yaml.

2. Branch

git checkout -b feature/my-thing

3. Run the app you are changing

pnpm dev:studio          # most common
# or
pnpm dev:docs
pnpm dev:www
pnpm dev:design-system

For Studio you usually also want a backing stack. Two options:

• Supabase CLI: pnpm setup:cli runs supabase start -x studio, generates keys.json, and writes a usable local .env.
• Self-host docker: cd docker && docker compose up -d, then mirror POSTGRES_PASSWORD and SUPABASE_SERVICE_KEY into apps/studio/.env.

4. Code

A few patterns are worth knowing up front (see Patterns and conventions for the long version):

• New data fetching → add a folder under apps/studio/data/<domain>/ with a *-query.ts (or *-mutation.ts) per operation, plus a keys.ts for query keys.
• New SQL generation → use or extend the helpers in packages/pg-meta/src/.
• New UI primitive → prefer _Shadcn_-suffixed components from packages/ui. If your component is generic, add it to packages/ui or packages/ui-patterns.
• New telemetry event → register it in packages/common/telemetry-constants.ts.

5. Verify locally

pnpm lint            # turbo run lint
pnpm typecheck       # tsc across the workspace
pnpm test:prettier   # formatting check

For Studio specifically:

pnpm test:studio
pnpm --filter studio lint:ratchet         # check the ratcheted rules
pnpm --filter studio lint:ratchet:type-checks

For UI / pattern packages:

pnpm test:ui
pnpm test:ui-patterns

E2E (only when the change is user-visible):

pnpm e2e:setup:cli   # boots local supabase + seeds it
pnpm e2e
# or pnpm e2e:ui for the Playwright UI runner

6. Commit

The repo uses conventional-commit-style messages, e.g. feat(studio): ..., fix(docs): ..., chore: .... PR titles follow the same shape; the squashed merge commit reuses the PR title.

7. Open a PR

• Push your branch and open a PR against master.
• Studio PRs auto-tag the frontend team.
• validate-pr.yml and the rest of .github/workflows/ will run lint, typecheck, prettier, unit tests, and (for relevant paths) the docs / studio e2e and ratchet checks.
• Vercel previews are triggered automatically (authorize-vercel-deploys.yml controls who can deploy).

8. Address review and merge

• Rebase on master if conflicts appear.
• A maintainer merges with squash; PR title becomes the merge commit message.

Common Turborepo tricks

• pnpm dev --filter <pkg>... → run dev for a package and everything that depends on it.
• pnpm clean → wipe node_modules, .next, .turbo, and Turborepo cache.
• pnpm typecheck --continue is the default — typecheck doesn't stop on the first failure.

Where things go after a merge

• Marketing site (apps/www) and design system: redeploys to Vercel automatically.
• Docs (apps/docs): Vercel auto-deploy, plus several scheduled workflows (docs-sync.yml, docs-lint-v2-scheduled.yml, docs-mgmt-api-update.yml).
• Studio: the hosted dashboard is deployed by the platform team out-of-band; the studio-docker-build.yml workflow publishes a new supabase/studio Docker image used by self-host.