The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
chore: split CLAUDE.md into root and studio-specific files (#48202)
Alaister Young2d5ec97df825
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.mdindex 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.mdindex 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/.gitignoreindex 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/.envdiff --git a/apps/studio/CLAUDE.md b/apps/studio/CLAUDE.mdnew file mode 100644index 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.mdindex 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.mdindex 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```