| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 7 | 5 | 0% |
| Commands | 0 | 13 | 0 | 0% |
| Section tags | 1 | 4 | 2 | 14% |
What each file covers
Sections
0 shared · 7 only in A · 5 only in B- − Supabase Monorepo
- − Structure
- − Common Commands
- − CI
- − Conventions
- − Skills
- − Studio
- + Studio Shortcut Review Rules
- + Core Principle
- + When to Flag
- + Preferred Pattern
- + Search Inputs
Commands
0 shared · 13 only in A · 0 only in B- − pnpm dev:studio
- − pnpm dev:docs
- − pnpm dev:www
- − pnpm test:studio
- − pnpm e2e
- − pnpm build --filter=studio
- − pnpm lint --filter=studio
- − pnpm typecheck
- − pnpm format
- − pnpm generate:types
- − pnpm api:codegen
- − eslint-config-supabase
- − vitest
Section tags
1 shared · 4 only in A · 2 only in B- − test
- − lint-format
- − architecture
- − monorepo
- + git-pr
- + do-not
- code-style
Line diff
supabase/supabase · .claude/CLAUDE.md
@@ −1 @@
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
supabase/supabase · .github/instructions/studio-shortcuts.instructions.md
@@ +1 @@
1---
2applyTo: 'apps/studio/**'
3---
4
5# Studio Shortcut Review Rules
6
7All comments are **advisory**.
8
9## Core Principle
10
11When Studio UI changes introduce or materially alter repeated user actions, consider whether keyboard shortcut coverage should be added or updated. Shortcuts should use the shared Studio shortcut system and be discoverable from the visible UI.
12
13## When to Flag
14
15- PR adds a primary repeated action, toolbar action, list/table operation, or sub-page navigation without considering shortcut coverage.
16- PR adds a one-off `keydown` listener for a normal Studio action instead of using the shortcut registry and `useShortcut`.
17- PR registers a shortcut but does not expose it via `ShortcutTooltip`, `ShortcutBadge`, or command-menu badge where the action is visible.
18- PR uses `G then ...` for a non-navigation action.
19- PR adds a broad `Mod+letter` shortcut that overlaps common browser, editor, system, copy/save/search, or devtools behaviour.
20- PR adds a shortcut without checking existing registry and non-registry listeners for collisions.
21- PR adds a search/filter `<Input>` without `onKeyDown={onSearchInputEscape(...)}` — see **Search Inputs** below.
22
23## Preferred Pattern
24
25- Add definitions in `apps/studio/state/shortcuts/registry.ts` or `apps/studio/state/shortcuts/registry/*`.
26- Register with `useShortcut`.
27- Gate availability with `enabled`.
28- Surface visible actions with `ShortcutTooltip` or `ShortcutBadge`.
29- Prefer scoped, mnemonic sequential chords over global modifier chords.
30- Set `showInSettings: false` on contextual shortcuts (scoped to a specific page state, sheet, or panel).
31- When a shortcut group should appear in the reference sheet (`Mod+/`), add the group key to `SHORTCUT_REFERENCE_GROUP_ORDER` in `apps/studio/state/shortcuts/referenceGroups.ts` and a human label to `GROUP_LABELS` in `ShortcutsReferenceSheet.tsx`.
32- For sheet-scoped shortcuts (active only while a `<Sheet>` is open), mount `useShortcut` inside the sheet component gated by the `open` prop — see `apps/studio/components/interfaces/ConnectSheet/useConnectSheetShortcut.ts` as the canonical example.
33
34## Search Inputs
35
36Every `<Input>` used as a search or filter field must include the staged-Escape handler from `apps/studio/lib/keyboard.ts`:
37
38```tsx
39import { onSearchInputEscape } from '@/lib/keyboard'
40
41;<Input
42 value={query}
43 onChange={(e) => setQuery(e.target.value)}
44 onKeyDown={onSearchInputEscape(query, setQuery)}
45/>
46```
47
48Behaviour:
49
50- **Escape while the input has a value** → clears the value, keeps focus (so a second Escape then blurs)
51- **Escape while the input is empty** → blurs the input
52- Stops propagation on Escape so the keystroke does not accidentally close a parent dialog or sheet
53
54When pairing with `useShortcut(LIST_PAGE_FOCUS_SEARCH, ...)` to focus a search input via keyboard, always also add `onSearchInputEscape` on the same input — focus and escape-to-blur are always a pair.
55
56Canonical implementation context: `apps/studio/state/shortcuts/registry.ts`, `apps/studio/state/shortcuts/useShortcut.tsx`, and `apps/studio/components/ui/Shortcut*.tsx`
57
@@ −1 +1 @@
1−# Supabase Monorepo
1+---
2+applyTo: 'apps/studio/**'
3+---
24
3−pnpm 11 + Turborepo monorepo. Requires Node >= 22.13.
5+# Studio Shortcut Review Rules
46
5−## Structure
7+All comments are **advisory**.
68
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 |
9+## Core Principle
2310
24−## Common Commands
11+When Studio UI changes introduce or materially alter repeated user actions, consider whether keyboard shortcut coverage should be added or updated. Shortcuts should use the shared Studio shortcut system and be discoverable from the visible UI.
2512
26−```bash
27−pnpm dev:studio # run Studio dev server → http://localhost:8082
28−pnpm dev:docs # run docs dev server
29−pnpm dev:www # run www dev server
30−pnpm test:studio # Studio unit tests (vitest)
31−pnpm e2e # Studio E2E tests (playwright)
32−pnpm build --filter=studio # build Studio
33−pnpm lint --filter=studio # lint Studio
34−pnpm typecheck # typecheck all packages
35−pnpm format # Prettier write (check: pnpm test:prettier)
36−pnpm generate:types # local DB types → supabase/functions/common/database-types.ts
37−pnpm api:codegen # platform Management API types → packages/api-types
38−```
13+## When to Flag
3914
40−## CI
15+- PR adds a primary repeated action, toolbar action, list/table operation, or sub-page navigation without considering shortcut coverage.
16+- PR adds a one-off `keydown` listener for a normal Studio action instead of using the shortcut registry and `useShortcut`.
17+- PR registers a shortcut but does not expose it via `ShortcutTooltip`, `ShortcutBadge`, or command-menu badge where the action is visible.
18+- PR uses `G then ...` for a non-navigation action.
19+- PR adds a broad `Mod+letter` shortcut that overlaps common browser, editor, system, copy/save/search, or devtools behaviour.
20+- PR adds a shortcut without checking existing registry and non-registry listeners for collisions.
21+- PR adds a search/filter `<Input>` without `onKeyDown={onSearchInputEscape(...)}` — see **Search Inputs** below.
4122
42−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.
23+## Preferred Pattern
4324
44−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`.
25+- Add definitions in `apps/studio/state/shortcuts/registry.ts` or `apps/studio/state/shortcuts/registry/*`.
26+- Register with `useShortcut`.
27+- Gate availability with `enabled`.
28+- Surface visible actions with `ShortcutTooltip` or `ShortcutBadge`.
29+- Prefer scoped, mnemonic sequential chords over global modifier chords.
30+- Set `showInSettings: false` on contextual shortcuts (scoped to a specific page state, sheet, or panel).
31+- When a shortcut group should appear in the reference sheet (`Mod+/`), add the group key to `SHORTCUT_REFERENCE_GROUP_ORDER` in `apps/studio/state/shortcuts/referenceGroups.ts` and a human label to `GROUP_LABELS` in `ShortcutsReferenceSheet.tsx`.
32+- For sheet-scoped shortcuts (active only while a `<Sheet>` is open), mount `useShortcut` inside the sheet component gated by the `open` prop — see `apps/studio/components/interfaces/ConnectSheet/useConnectSheetShortcut.ts` as the canonical example.
4533
46−## Conventions
34+## Search Inputs
4735
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`.
36+Every `<Input>` used as a search or filter field must include the staged-Escape handler from `apps/studio/lib/keyboard.ts`:
4937
50−**Styling** — Tailwind only, semantic tokens (`bg-muted`, `text-foreground-light`), no hardcoded colors.
38+```tsx
39+import { onSearchInputEscape } from '@/lib/keyboard'
5140
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).
41+;<Input
42+ value={query}
43+ onChange={(e) => setQuery(e.target.value)}
44+ onKeyDown={onSearchInputEscape(query, setQuery)}
45+/>
46+```
5347
54−**Language** — Use U.S. English everywhere.
48+Behaviour:
5549
56−## Skills
50+- **Escape while the input has a value** → clears the value, keeps focus (so a second Escape then blurs)
51+- **Escape while the input is empty** → blurs the input
52+- Stops propagation on Escape so the keystroke does not accidentally close a parent dialog or sheet
5753
58−The skills in `.claude/skills/` are the source of truth for conventions — load the relevant ones before working, don't guess:
54+When pairing with `useShortcut(LIST_PAGE_FOCUS_SEARCH, ...)` to focus a search input via keyboard, always also add `onSearchInputEscape` on the same input — focus and escape-to-blur are always a pair.
5955
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−
70−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.
56+Canonical implementation context: `apps/studio/state/shortcuts/registry.ts`, `apps/studio/state/shortcuts/useShortcut.tsx`, and `apps/studio/components/ui/Shortcut*.tsx`
7157
