supabase/supabase

Studio

The Supabase dashboard. Built with Next.js (Pages Router), Tailwind CSS, React-Query, and a deep custom data layer. The same app is served at supabase.com/dashboard and ships as the supabase/studio Docker image used by self-hosted installs.

Purpose

Studio lets users manage one or more Supabase projects: tables, SQL editor, auth users and providers, storage buckets and objects, edge functions, replication, branches, advisors, logs, integrations, billing, and organization settings. It talks to either the Supabase platform / management API (when running on supabase.com) or directly to a self-hosted stack via Kong + postgres-meta.

Directory layout

apps/studio/
├── pages/                 # Next.js Pages Router routes
│   ├── project/           # Per-project dashboard
│   ├── org/               # Organization settings
│   ├── account/           # User account settings
│   ├── partners/          # Vercel / AWS marketplace flows
│   ├── api/               # Next.js API routes (server-side)
│   └── sign-in*.tsx       # Auth surfaces
├── components/
│   ├── interfaces/        # Per-feature UI (~48 folders)
│   ├── layouts/           # Page layouts
│   ├── ui/, ui-patterns/  # Studio-specific patterns
│   └── grid/              # Table editor (built on react-data-grid)
├── data/                  # ~92 React-Query domain folders
├── hooks/                 # Cross-cutting hooks
├── state/                 # Valtio stores
├── lib/                   # Helpers, constants, fetchers
├── evals/                 # Braintrust AI evals
├── eslint-rules/          # Custom ESLint rules
├── scripts/               # Codegen and ratchet scripts
├── instrumentation*.ts    # Sentry / OpenTelemetry init
├── next.config.ts         # Next.js + Sentry config
└── Dockerfile             # Used by self-host

Key abstractions

Type	File	Description
`fetcher`, `handleError`	`apps/studio/data/fetchers.ts`, `apps/studio/data/handleError.ts`	The single typed HTTP client used by every data hook. Wraps `openapi-fetch` against `packages/api-types`.
`*Keys` factory	`apps/studio/data/<domain>/keys.ts`	Strongly-typed React-Query key generators per domain.
`useXQuery` / `useXMutation`	`apps/studio/data/<domain>/<entity>-{query,mutation}.ts`	Wraps `useQuery` / `useMutation` with a stable interface and error normalization.
`LayoutWith*`	`apps/studio/components/layouts/`	Shells for project, org, account, partner-portal pages.
Studio Assistant	`apps/studio/components/interfaces/Docs/`, `apps/studio/data/ai/`	The in-product LLM assistant; uses `packages/ai-commands` and the AI SDK.
`Sidebar.tsx`	`apps/studio/components/interfaces/Sidebar.tsx`	The product nav. Drives feature-flagged routes.
`instrumentation-client.ts`	`apps/studio/instrumentation-client.ts`	Sentry init + custom error filtering. ~12 KB; routinely audited.

Major feature folders under `components/interfaces/`

Folder	Surface
`Auth/`	Users list, providers, hooks, MFA, sign-in policy, magic-link / OTP / SSO.
`Database/`	Tables, columns, indexes, triggers, functions, extensions, replication, cron, queues, vault.
`SQLEditor/`	Tabs, snippets, AI-generated SQL, query history, formatter, explain.
`TableGridEditor/`	The data grid (built on a patched `react-data-grid`). Inline editing, foreign-key picker, RLS impersonation.
`Storage/`	Buckets, files, S3 access keys, image transformations, vector buckets, Iceberg wrappers.
`EdgeFunctions/`	Editor, deploy, logs, secrets.
`Functions/`	Database functions UI.
`Realtime/`	Inspector for channels and presence.
`Reports/`, `QueryPerformance/`, `QueryInsights/`	Observability views over Logflare.
`UnifiedLogs/`	The cross-product logs explorer.
`Auth/`, `APIKeys/`, `JwtSecrets/`, `JitDbAccess/`	Project security surfaces.
`Billing/`	Plans, invoices, usage, Stripe-backed flows.
`BranchManagement/`	Database branches on the hosted product.
`Integrations/`	Vercel, GitHub, partner marketplace.
`Connect/`, `ConnectSheet/`	The "Connect to your project" sheet (connection strings, client snippets).
`Advisors/`, `Linter/`	The schema/security advisors.
`Settings/`	Project and organization settings; feature previews live here.

How it works

Studio is a Pages Router Next.js app. Most pages render quickly with no SSR data — data comes from React-Query hooks once the page mounts. The data flow:

graph LR
    Page[apps/studio/pages/*]
    Component[components/interfaces/...]
    Hook["data/&lt;domain&gt;/use*Query"]
    Fetcher[data/fetchers.ts]
    PgMeta[packages/pg-meta]
    Platform[Platform / Mgmt API]
    Postgres[(Postgres)]

    Page --> Component
    Component --> Hook
    Hook --> Fetcher
    Hook --> PgMeta
    Fetcher -->|openapi-fetch + types| Platform
    PgMeta -->|generated SQL| Fetcher
    Fetcher --> Postgres

Studio's auth runs through packages/common/auth.tsx and packages/common/gotrue.ts. Build-time auth mode is selected by NEXT_PUBLIC_STUDIO_AUTH_MODE (supabase for hosted, none for self-host).

Integration points

Imports from packages/api-types for typed access to the platform / management API.
Imports from packages/pg-meta for SQL generation against the project's Postgres.
Imports from packages/ai-commands (server-only and edge subpaths) for Assistant features.
Imports from packages/common, packages/ui, packages/ui-patterns, packages/icons for shared infrastructure and components.
Self-host: built into a Docker image by studio-docker-build.yml; consumed by docker/docker-compose.yml's studio service.

Entry points for modification

New product feature → create a folder under components/interfaces/<Feature> and a sibling folder under data/<feature>/. Add the route in pages/project/[ref]/....
New data fetcher → follow the *-query.ts / *-mutation.ts / keys.ts pattern in any existing folder; reuse data/fetchers.ts.
New SQL — extend packages/pg-meta rather than writing inline SQL strings.
Sidebar nav — components/interfaces/Sidebar.tsx and the route metadata in lib/.

Tests

Studio's tests are a mix of Vitest unit tests (*.test.ts(x) next to the source), MSW-backed component tests, and Playwright e2e in e2e/studio. Coverage is tracked under apps/studio/coverage/. AI behavior is tested via Braintrust evals in apps/studio/evals/.

See how-to-contribute/testing.md for the full layout and run commands.

Cross-references

packages/api-types — typed platform API client.
packages/pg-meta — SQL generators.
packages/ai-commands — Assistant prompts.
packages/common — auth, telemetry, feature flags.
packages/ui — shared component library.
Self-host — how Studio is shipped to self-host.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.