Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

chore: split CLAUDE.md into root and studio-specific files (#48202)

Alaister Young2d5ec97df825
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index ca29fe71fba..175aec83c51 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,42 +1,70 @@
# Supabase Monorepo
-pnpm 10 + Turborepo monorepo. Requires Node >= 22.
+pnpm 11 + Turborepo monorepo. Requires Node >= 22.13.
## Structure
-| Directory | Purpose |
-| ----------------- | ------------------------------------------------------------ |
-| `apps/studio` | Supabase Studio/Dashboard — Next.js (pages router), React 19 |
-| `apps/docs` | Documentation site |
-| `apps/www` | Marketing website |
-| `packages/ui` | Shared UI components (shadcn/ui based) |
-| `packages/common` | Shared utilities and telemetry constants |
-| `e2e/studio` | Playwright E2E tests for Studio |
+| Directory | Purpose |
+| ------------------------ | --------------------------------------------------------------------------- |
+| `apps/studio` | Supabase Studio/Dashboard — has its own `apps/studio/CLAUDE.md` (see below) |
+| `apps/docs` | Documentation site — Next.js app router, MDX (port 3001) |
+| `apps/www` | Marketing website — Next.js, app + pages (port 3000) |
+| `apps/design-system` | Component demos — source of truth for Studio UI patterns (port 3003) |
+| `apps/ui-library` | shadcn-style registry site for Supabase UI blocks (port 3004) |
+| `apps/lite-studio` | Lightweight Studio — different stack: React Router 7 + Vite + Tailwind v4 |
+| `packages/ui` | Shared UI components (shadcn/ui based) — `import { Button } from 'ui'` |
+| `packages/ui-patterns` | Composite components — subpath imports, e.g. `ui-patterns/AssistantChat` |
+| `packages/common` | Shared utils, telemetry constants, feature flags |
+| `packages/api-types` | Generated platform Management API types |
+| `packages/pg-meta` | SQL builders for Postgres introspection (`SafeSqlFragment`) |
+| `packages/shared-data` | Static data: pricing, plans, regions, error codes |
+| `e2e/studio`, `e2e/docs` | Playwright E2E tests |
+| `supabase/` | Local Supabase project: edge functions, migrations, config.toml |
## Common Commands
```bash
-pnpm install # install dependencies
-pnpm dev:studio # run Studio dev server
-pnpm test:studio # run Studio unit tests (vitest)
-pnpm --prefix e2e/studio run e2e # run Studio E2E tests (playwright)
-pnpm build --filter=studio # build Studio
-pnpm lint --filter=studio # lint Studio
-pnpm typecheck # typecheck all packages
+pnpm install # install dependencies
+pnpm dev:studio # run Studio dev server → http://localhost:8082
+pnpm dev:docs # run docs dev server
+pnpm dev:www # run www dev server
+pnpm test:studio # Studio unit tests (vitest)
+pnpm e2e # Studio E2E tests (playwright)
+pnpm build --filter=studio # build Studio
+pnpm lint --filter=studio # lint Studio
+pnpm typecheck # typecheck all packages
+pnpm format # Prettier write (check: pnpm test:prettier)
+pnpm generate:types # local DB types → supabase/functions/common/database-types.ts
+pnpm api:codegen # platform Management API types → packages/api-types
```
+## CI
+
+Every 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.
+
+Never 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`.
+
## Conventions
-**UI** — import from `'ui'`, use `_Shadcn_` suffixed variants for form primitives. Check `packages/ui/index.tsx` before creating new primitives.
+**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`.
**Styling** — Tailwind only, semantic tokens (`bg-muted`, `text-foreground-light`), no hardcoded colors.
+**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).
+
**Language** — Use U.S. English everywhere.
-**Studio shortcuts** — when adding or changing repeated Studio UI actions, use the shared shortcut registry and primitives in `apps/studio/state/shortcuts/` and `apps/studio/components/ui/Shortcut*.tsx`. Prefer registered, discoverable shortcuts over one-off keyboard listeners; keep `G then ...` chords for navigation.
+## Skills
-## Studio
+The skills in `.claude/skills/` are the source of truth for conventions — load the relevant ones before working, don't guess:
+
+- `copywriting` — any user-facing text, anywhere in the monorepo
+- `docs-content` — anything under `apps/docs`
+- `telemetry-standards` — PostHog events, `packages/common/telemetry-constants.ts`
+- `dev-toolbar-review` — `packages/dev-tools`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`
+- `safe-sql-execution` — any code that builds or executes SQL against user databases
+- `vitest` / `vercel-composition-patterns` — generic unit-testing and React composition references
-Pages router. Co-locate sub-components with parent. Avoid barrel re-export files.
+## Studio
-See studio-\* skills for detailed studio conventions.
+Before 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.
diff --git a/.claude/skills/studio-ui-patterns/SKILL.md b/.claude/skills/studio-ui-patterns/SKILL.md
index c929e767a13..cc875ec5710 100644
--- a/.claude/skills/studio-ui-patterns/SKILL.md
+++ b/.claude/skills/studio-ui-patterns/SKILL.md
@@ -34,7 +34,7 @@ Docs: `apps/design-system/content/docs/ui-patterns/forms.mdx`
- Use `react-hook-form` + `zod`
- Use `FormItemLayout` instead of manually composing `FormItem`/`FormLabel`/`FormMessage`/`FormDescription`
-- Wrap inputs with `FormControl`; use `_Shadcn_` imports from `ui` for primitives
+- Wrap inputs with `FormControl`; import primitives from `ui`
Layout selection:
diff --git a/.gitignore b/.gitignore
index ce23cae5706..f6689369010 100644
--- a/.gitignore
+++ b/.gitignore
@@ -123,8 +123,8 @@ next-env.d.ts
!.claude/scripts/
!.claude/skills/
.claude/skills/me-*
-CLAUDE.md
!.claude/CLAUDE.md
+CLAUDE.local.md
#include template .env file for docker-compose
!docker/.env
diff --git a/apps/studio/CLAUDE.md b/apps/studio/CLAUDE.md
new file mode 100644
index 00000000000..e102a63417e
--- /dev/null
+++ b/apps/studio/CLAUDE.md
@@ -0,0 +1,53 @@
+# Supabase Studio
+
+Next.js pages router + TanStack Start (mid-migration, see below), React 19. Dev server: `pnpm dev:studio` → http://localhost:8082.
+
+## Skills — load before working
+
+**Always load the `studio-best-practices` skill before writing or modifying any Studio code.** Then stack the area-specific skills:
+
+| Task | Additional skills |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| Query/mutation hooks, query keys (`data/**`) | `studio-queries` |
+| UI: pages, forms, tables, charts, sheets, empty states | `studio-ui-patterns` |
+| Displaying API errors | `studio-error-handling` |
+| Tests (deciding, writing, reviewing) | `studio-testing`, then `studio-mock-api-tests` (component/MSW) or `studio-e2e-tests` (Playwright) |
+| PostHog event tracking | `telemetry-standards` |
+| SQL against user databases | `safe-sql-execution` |
+| Logs Explorer SQL, `data/logs` | `clickhouse-logs-queries` |
+| Component API design, boolean-prop refactors | `vercel-composition-patterns` |
+| User-facing copy | `copywriting` |
+
+## TanStack Start migration
+
+Studio is migrating from the Next.js pages router (`pages/**`) to TanStack Start (`routes/**`). Both runtimes ship side-by-side; the `STUDIO_FRAMEWORK` env var selects which one `pnpm dev`/`build` runs (default: `next`, resolved in `scripts/dispatch.js`). Full route map and strategy: `TANSTACK_MIGRATION.md`.
+
+- **Never delete a page file.** Most `routes/**` files are thin wrappers re-exporting the default export of their `pages/**` counterpart, so the Next file is load-bearing for both runtimes until the final cleanup pass.
+- Pure page-body edits propagate to the route automatically. Mirror a change by hand into the corresponding `routes/**` file only when it touches what the route duplicates: `getLayout`/layout wrapping, page titles or other `staticData` (incl. `skip*Layout` flags), `withAuth`, or redirect paths.
+- A new page under `pages/**` needs a matching route under `routes/**` plus a checklist entry in `TANSTACK_MIGRATION.md`.
+- New code uses native TanStack APIs — no `next/router` or `next/link`. The `compat/next/` shims exist only for legacy re-exported pages.
+- `routeTree.gen.ts` is generated by the Vite plugin — never hand-edit.
+
+## Orientation
+
+- **Data layer** — all platform API calls go through `data/fetchers.ts` (`openapi-fetch`, typed by the generated `api-types` package) with `handleError`; never raw `fetch`. One folder per resource in `data/`, most with a `keys.ts` query-key factory.
+- **State** — valtio for global state (`state/`), nuqs for URL state, react-hook-form + zod for forms.
+- **Platform vs self-hosted** — `IS_PLATFORM` gates platform-only behavior; `withAuth` is a no-op when self-hosted.
+- **Telemetry** — `useTrack()` from `lib/telemetry/track`; event types live in `packages/common/telemetry-constants.ts`.
+- **Tests** — default to including relevant tests with any change: a couple of unit tests for extracted logic, component tests for UI behavior, E2E only when the scope demands it (`studio-testing` has the decision tree). Not every PR needs them, but "no tests" should be a considered choice, not the default. Tooling: vitest + MSW; component tests use `customRender` + `addAPIMock` from `tests/lib/`; unhandled network requests fail tests. Don't `vi.mock('@/data/...')`.
+- **Shortcuts** — use the registry in `state/shortcuts/` and `components/ui/Shortcut*.tsx`; keep `G then …` chords for navigation; no one-off keyboard listeners.
+- **Reuse first** — before writing a new hook or helper, search for an existing one (`hooks/`, `lib/`, `packages/common`, `packages/ui-patterns`). If you do need a new one, make it as reusable as possible: general naming, no page-specific coupling, placed where other callers can find it.
+- Co-locate sub-components with their parent; avoid barrel re-export files.
+
+## Defaults that differ here
+
+- **ESLint warnings are ratcheted in CI**: the per-rule occurrence count must not increase, so a new `any`, unresolved `exhaustive-deps` warning, or default export fails the build even though it's "only a warning". Check locally with `pnpm --filter studio run lint:ratchet`.
+- **Clipboard**: `copyToClipboard` from `'ui'`, and never `await` anything before calling it (Safari requires the write inside the user gesture; lint-enforced) — pass a Promise as the argument instead.
+- **`useParams()` comes from `'common'`**, not `next/navigation` — it camelCases keys and returns `string | undefined`.
+- **Permissions**: `useAsyncCheckPermissions` from `hooks/misc/useCheckPermissions` (returns `can: true` when self-hosted).
+- **Gating**: `useIsFeatureEnabled` for product features, `useFlag` from `'common'` for feature flags — two different systems.
+- **Dates**: `dayjs` (plugins pre-loaded at both entries, `pages/_app.tsx` and `routes/__root.tsx`), not `date-fns`. **Toasts**: `toast` from `'sonner'`.
+- **Import split**: `'ui'` = primitives, `'ui-patterns'` = composed patterns (`ConfirmationModal`, …), `@ui/*` = alias into `packages/ui/src`. Icons come from `lucide-react`.
+- **New tables** use `@tanstack/react-table`; `react-data-grid` is banned for new code.
+- **Ad-hoc SQL** against the user's database goes through `executeSql` / `useExecuteSqlMutation` (`data/sql/execute-sql-mutation`).
+- **Confirmations**: `ConfirmationModal` / `TextConfirmModal` from `ui-patterns`, never `window.confirm`. Disabled buttons needing an explanation use `ButtonTooltip`; inline warnings use `Admonition`.
diff --git a/apps/studio/TANSTACK_MIGRATION.md b/apps/studio/TANSTACK_MIGRATION.md
index 5afb7202e9e..387e808c2ce 100644
--- a/apps/studio/TANSTACK_MIGRATION.md
+++ b/apps/studio/TANSTACK_MIGRATION.md
@@ -599,4 +599,5 @@ for the Vite pipeline:
- Delete `pages/_app.tsx`, `pages/_document.tsx`, `pages/_error.jsx`, `pages/500.tsx`, `pages/404.tsx` (Next-only catch-alls; TanStack equivalents on `__root.tsx`).
- Drop the `dev:next` / `build:next` / `start:next` scripts from `apps/studio/package.json` once we're committed to TanStack.
- Remove the `apps/studio/pages/**` `path_instructions` guardrail entry from `.coderabbit.yaml` (added in FE-3423; remove it as part of this FE-3106 cleanup) — it's only useful while both runtimes coexist.
+- Remove the "TanStack Start migration" section from `apps/studio/CLAUDE.md` — it only applies while both runtimes coexist.
- Delete this file.
diff --git a/apps/studio/components/README.md b/apps/studio/components/README.md
index c5d618a74b1..e9127e56d0b 100644
--- a/apps/studio/components/README.md
+++ b/apps/studio/components/README.md
@@ -35,10 +35,8 @@ interface ComponentAProps {
sampleProp: string
}
-// Name your component accordingly
-const ComponentA = ({ sampleProp }: ComponentAProps) => {
+// Name your component accordingly — use a named export, not a default export
+export const ComponentA = ({ sampleProp }: ComponentAProps) => {
return <div>ComponentA: {sampleProp}</div>
}
-
-export default ComponentA
```