CLAUDE.md

1# Supabase Monorepo
2 
3pnpm 11 + Turborepo monorepo. Requires Node >= 22.13.
4 
5## Structure
6 
7| Directory                | Purpose                                                                     |
8| ------------------------ | --------------------------------------------------------------------------- |
9| `apps/studio`            | Supabase Studio/Dashboard — has its own `apps/studio/CLAUDE.md` (see below) |
10| `apps/docs`              | Documentation site — Next.js app router, MDX (port 3001)                    |
11| `apps/www`               | Marketing website — Next.js, app + pages (port 3000)                        |
12| `apps/design-system`     | Component demos — source of truth for Studio UI patterns (port 3003)        |
13| `apps/ui-library`        | shadcn-style registry site for Supabase UI blocks (port 3004)               |
14| `apps/lite-studio`       | Lightweight Studio — different stack: React Router 7 + Vite + Tailwind v4   |
15| `packages/ui`            | Shared UI components (shadcn/ui based) — `import { Button } from 'ui'`      |
16| `packages/ui-patterns`   | Composite components — subpath imports, e.g. `ui-patterns/AssistantChat`    |
17| `packages/common`        | Shared utils, telemetry constants, feature flags                            |
18| `packages/api-types`     | Generated platform Management API types                                     |
19| `packages/pg-meta`       | SQL builders for Postgres introspection (`SafeSqlFragment`)                 |
20| `packages/shared-data`   | Static data: pricing, plans, regions, error codes                           |
21| `e2e/studio`, `e2e/docs` | Playwright E2E tests                                                        |
22| `supabase/`              | Local Supabase project: edge functions, migrations, config.toml             |
23 
24## Common Commands
25 
26```bash
27pnpm dev:studio              # run Studio dev server → http://localhost:8082
28pnpm dev:docs                # run docs dev server
29pnpm dev:www                 # run www dev server
30pnpm test:studio             # Studio unit tests (vitest)
31pnpm e2e                     # Studio E2E tests (playwright)
32pnpm build --filter=studio   # build Studio
33pnpm lint --filter=studio    # lint Studio
34pnpm typecheck               # typecheck all packages
35pnpm format                  # Prettier write (check: pnpm test:prettier)
36pnpm generate:types          # local DB types → supabase/functions/common/database-types.ts
37pnpm api:codegen             # platform Management API types → packages/api-types
38```
39 
40## CI
41 
42Every PR must pass typecheck + lint (one workflow), Prettier, and a typos check. Other checks are path-filtered: Studio unit tests/build and the lint ratchet (ESLint warning count must not increase) run on `apps/studio/**` changes; app-specific test suites run on their own paths.
43 
44Never hand-edit generated files: `packages/api-types/types/**`, `**/routeTree.gen.ts`, `**/__generated__/**`, `apps/docs/features/docs/generated/**`, `apps/www/.generated/**`, `supabase/functions/common/database-types.ts`.
45 
46## Conventions
47 
48**UI** — import from `'ui'`; primitives are shadcn/ui-based and exported unsuffixed (`Input`, `Select`, `Form`, …). Use `Button` — the in-house component and the standard everywhere (a raw shadcn `Button_Shadcn_` also exists but is rarely the right choice). Check `packages/ui/index.tsx` before creating new primitives. Higher-level patterns live in `packages/ui-patterns`.
49 
50**Styling** — Tailwind only, semantic tokens (`bg-muted`, `text-foreground-light`), no hardcoded colors.
51 
52**Exports** — named exports only; default exports are allowed only where a framework requires them (`pages/**`, `app/**`, config files — the eslint preset has the exact carve-out list). Lint-enforced across all apps via `eslint-config-supabase` (severity `warn` everywhere; hard-enforced in Studio by the lint ratchet).
53 
54**Language** — Use U.S. English everywhere.
55 
56## Skills
57 
58The skills in `.claude/skills/` are the source of truth for conventions — load the relevant ones before working, don't guess:
59 
60- `copywriting` — any user-facing text, anywhere in the monorepo
61- `docs-content` — anything under `apps/docs`
62- `telemetry-standards` — PostHog events, `packages/common/telemetry-constants.ts`
63- `dev-toolbar-review` — `packages/dev-tools`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`
64- `safe-sql-execution` — any code that builds or executes SQL against user databases
65- `react-hook-form` — writing or modifying any form code, anywhere in the monorepo
66- `vitest` / `vercel-composition-patterns` — generic unit-testing and React composition references
67 
68## Studio
69 
70Before working on anything in `apps/studio`, read `apps/studio/CLAUDE.md` if it isn't already in context — it maps Studio tasks to required skills and covers the TanStack Start migration rules.
71