Supabase Monorepo Wiki

Overview

Supabase is the Postgres development platform, providing Firebase-like features using enterprise-grade open source tools. This monorepo contains the complete Supabase ecosystem: the hosted platform, dashboard, documentation, and supporting packages.

Core Architecture

Supabase combines several open source components into a unified platform:

• Postgres – The foundational relational database with 30+ years of proven reliability
• PostgREST – Auto-generates RESTful APIs directly from your database schema
• GoTrue – JWT-based authentication API for user management
• Realtime – Elixir server enabling WebSocket subscriptions to database changes
• Storage – RESTful API for file management with S3 backend and Postgres permissions
• pg_graphql – PostgreSQL extension exposing a GraphQL API
• postgres-meta – RESTful API for database administration and introspection
• Kong – Cloud-native API gateway routing requests

Repository Structure

This is a Turborepo monorepo using pnpm workspaces. The structure includes:

apps/
  ├── www              # Main marketing website (supabase.com)
  ├── studio           # Dashboard UI (supabase.com/dashboard)
  ├── docs             # Documentation site (supabase.com/docs)
  ├── cms              # Content management system for blog
  ├── design-system    # Design system documentation
  └── ui-library       # Component library showcase

packages/
  ├── ui               # Shared UI components
  ├── common           # Common React utilities
  ├── config           # Shared configuration
  ├── ai-commands      # AI-related helpers
  ├── pg-meta          # Postgres metadata client
  └── [others]         # Additional shared packages

Development Stack

• Language: TypeScript
• Package Manager: pnpm 10.24+
• Node Version: 22.x or higher
• Build Tool: Turbo for monorepo orchestration
• Frameworks: Next.js for web apps, React for UI components
• Styling: Tailwind CSS
• Containerization: Docker for local Supabase instance

Key Commands

pnpm install          # Install all dependencies
pnpm dev              # Start all apps in parallel
pnpm dev:www          # Start marketing website only
pnpm dev:studio       # Start dashboard (requires Docker)
pnpm build            # Build all apps
pnpm lint             # Lint entire monorepo
pnpm typecheck        # Type-check all TypeScript

Local Development Workflow

1. Setup: Clone repo, install pnpm, run pnpm install
2. Environment: Copy .env.local.example to .env.local in relevant app directories
3. Docker: For Studio development, run docker compose up in the /docker directory
4. Development: Use pnpm dev to start all apps or pnpm dev:www for specific apps
5. Access: Visit http://localhost:3000 (www), http://localhost:8082 (studio), or http://localhost:3001/docs (docs)

Deployment & Build Configuration

Turbo tasks are configured in turbo.json with environment variables and output caching. Each app (cms, studio, www, design-system, ui-library) has specific build dependencies and environment requirements. The build system supports parallel execution and incremental builds for faster iteration.

Architecture & Monorepo Structure

This repository is a monorepo managed with pnpm workspaces and Turbo for build orchestration. It contains the Supabase platform, including the dashboard, documentation, and shared libraries.

Monorepo Structure

The workspace is organized into four main directories:

• apps/ - Production applications and websites

  • studio - Supabase Dashboard (Next.js) for managing projects
  • www - Marketing website (supabase.com)
  • docs - Reference documentation and API specs
  • cms - Content management system for blog and marketing
  • design-system - Design system showcase
  • ui-library - UI component library documentation

• packages/ - Shared libraries and utilities

  • ui - Core UI component library (shadcn-based)
  • common - Shared utilities, auth, telemetry, and feature flags
  • config - Tailwind and ESLint configurations
  • api-types - TypeScript types for APIs
  • pg-meta - PostgreSQL metadata utilities
  • icons - Icon library
  • ai-commands - AI command utilities

• blocks/ - Reusable code blocks and examples

• e2e/ - End-to-end tests

Build System: Turbo

Turbo orchestrates builds across the monorepo with task dependencies. Key tasks:

• build - Compiles all applications and packages
• dev - Runs all development servers in parallel
• lint - Lints code across the workspace
• test - Runs tests for specific packages
• typecheck - Type-checks TypeScript code

Each app has specific environment variables defined in turbo.json for builds. For example, studio#build requires 100+ environment variables for features like Stripe, Sentry, and ConfigCat.

Package Management: pnpm

The workspace uses pnpm 10.24 with a shared dependency catalog in pnpm-workspace.yaml. This ensures consistent versions across all packages:

• React 18.3, Next.js 15.5, TypeScript 5.9
• Tailwind CSS 3.4, Vite 7.1, Vitest 3.2
• Supabase client libraries (auth-js, postgrest-js, realtime-js)

The catalog prevents version conflicts and simplifies dependency management.

Development Workflow

# Install dependencies
pnpm install

# Run all dev servers
pnpm dev

# Run specific app
pnpm dev:studio

# Build all
pnpm build

# Run tests
pnpm test:studio

Key Architectural Patterns

Shared Dependencies: Common packages like @supabase/auth-js and tailwindcss are defined once in the catalog and reused across all apps.

Task Caching: Turbo caches build outputs (.next/, dist/) to speed up rebuilds. The clean task clears all caches.

Environment Isolation: Each app has its own environment configuration. Studio and www have the most complex setups with 100+ environment variables for integrations.

TypeScript Configuration: Shared base configs in packages/tsconfig/ are extended by each app for consistency.

Studio Dashboard Application

Supabase Studio is a comprehensive web dashboard built with Next.js and Tailwind CSS for managing Supabase projects. It serves as the primary interface for both self-hosted deployments and the hosted platform at supabase.com/dashboard.

Core Architecture

The application uses a Next.js Pages Router with a modular component structure:

• Pages (/pages) - Route handlers organized by feature (database, auth, storage, API docs)
• Components (/components) - Organized into three categories:
  • layouts/ - Page structure and layout components
  • interfaces/ - Feature-specific components tightly coupled to pages
  • ui/ - Reusable components across the dashboard
• State Management (/state) - Valtio-based reactive state for UI and data
• Data Layer (/data) - React Query hooks for API communication

Key Features

Studio provides database-focused management capabilities:

• Table & SQL Editors - Visual table editor and SQL query interface
• Database Management - Policies, roles, extensions, replication configuration
• API Documentation - Auto-generated REST API docs with language-specific examples
• Observability - Analytics, logs, and monitoring dashboards
• Storage Management - File bucket management and analytics
• Authentication - User management and auth configuration

Data Flow & Client Setup

The dashboard connects to Supabase projects using temporary API keys:

// Creates a project-specific Supabase client
const client = await createProjectSupabaseClient(projectRef, endpoint)
// Uses temporary API key for secure, session-less authentication

React Query manages all server state with intelligent retry logic:

// Configured with 1-minute stale time and smart retry strategies
// Skips retries on 4xx errors (except 429 rate limits)
// Respects rate limit backoff headers

State Management Patterns

The dashboard uses Valtio proxies for reactive UI state:

• table-editor.tsx - Table editing state (rows per page, side panels, confirmations)
• ai-assistant-state.tsx - AI chat sessions stored in IndexedDB
• app-state.ts - Global app state (sidebar visibility, mobile menu)

Layout System

The application uses a resizable panel layout with responsive behavior:

• ProjectLayout - Main dashboard with collapsible sidebar and content area
• OrganizationLayout - Organization-level pages with partner integration alerts
• DefaultLayout - Standard page wrapper for non-project pages

Feature flags and role impersonation enable fine-grained access control across the dashboard.

Shared Packages & Libraries

The Supabase monorepo uses a modular package structure to share code across multiple applications. These shared packages are published as workspace dependencies and consumed by apps like Studio, the marketing website, and documentation.

Core UI & Component Libraries

ui - The foundational component library built on shadcn/ui and Radix UI primitives. It exports 100+ components including buttons, forms, dialogs, tabs, and data display components. Uses Figma tokens transformed into CSS variables and Tailwind classes for theming support. Includes hooks for common UI patterns.

ui-patterns - Higher-level components built from ui package components and external libraries like react-markdown and reactflow. Designed for components used in only 1-2 apps to avoid bloating all applications. Uses granular exports (e.g., ui-patterns/CommandMenu) rather than a barrel file to enable tree-shaking.

icons - Custom Supabase icon library with SVG-based icons. Add new icons by placing SVG files in src/raw-icons/ and running npm run build:icons.

Shared Utilities & Data

common - React utilities and hooks shared across all sites. Exports authentication helpers, feature flags (ConfigCat integration), telemetry (PostHog), consent management, database types, and Providers component. Depends on api-types and config packages.

shared-data - Static data constants used across applications: pricing plans, product information, AWS/Fly regions, extensions, log constants, and tweets. Provides TypeScript types for region data and pricing information.

api-types - Generated TypeScript types from OpenAPI specifications. Combines Supabase API and Platform API types. Regenerate with npm run codegen when API specs change.

Configuration & Infrastructure

config - Shared Tailwind CSS and ESLint configurations. Exports Tailwind plugins, color tokens from Radix UI, and form/typography utilities. Used as a dependency by ui and common.

tsconfig - Base TypeScript configurations inherited by all workspace packages. Includes presets for Next.js apps, React libraries, and general projects.

Specialized Packages

ai-commands - AI and LLM utilities for features like SQL generation and policy assistance. Streaming functions require Edge runtime and must be imported via ai-commands/edge subpath.

pg-meta - PostgreSQL metadata client for querying database schema information. Exports utilities for tables, columns, functions, policies, triggers, and other database objects. Used by Studio for database introspection.

Dependency Graph

Loading diagram...

Workspace Dependencies

All packages use workspace:* protocol in package.json for local dependencies, enabling automatic version management and symlinked development. Install dependencies in a specific workspace by navigating to it and running pnpm add package-name.

Web Presence & Documentation

The web presence consists of four interconnected applications that serve different purposes in the Supabase ecosystem.

Main Website (apps/www)

The primary marketing and information hub built with Next.js 15 and MDX. It features:

• Marketing content: Product pages, pricing, features, and comparisons
• Blog platform: Hundreds of articles with authors, categories, and tags
• Customer stories: Case studies and testimonials from Supabase users
• Events: Launch weeks, hackathons, and community meetups
• Dynamic components: Interactive demos, carousels, and data visualizations using Framer Motion and Recharts

The site uses Supabase for backend services and integrates with Payload CMS for live preview capabilities. Content is generated statically and deployed to Vercel with automatic sitemap generation.

Reference Documentation (apps/docs)

A comprehensive technical documentation site with versioned docs for multiple tools:

• API Reference: OpenAPI specifications for REST endpoints
• SDK Documentation: Versioned docs for JavaScript, Python, Dart, Swift, Kotlin, and C# SDKs
• CLI Reference: Command documentation with ConfigSpec and CLISpec formats
• Guides: Step-by-step tutorials and best practices
• Troubleshooting: Error codes and common issues

Uses custom DocSpec formats (OpenAPI, SDKSpec, ConfigSpec, CLISpec) to generate human-readable documentation. This allows switching documentation systems while maintaining a single source of truth. Built with Next.js and includes GraphQL schema generation, embeddings for search, and smoke tests for production validation.

Content Management System (apps/cms)

Payload CMS instance for managing blog posts, events, authors, and media:

• Collections: Authors, Categories, Events, Media, Posts, Tags, Users
• Storage: Integrates with Supabase Storage via S3 plugin
• Rich editing: Lexical-based rich text editor with form builder
• SEO: Built-in SEO plugin for metadata management
• Live preview: Real-time preview integration with www and docs apps

Runs on port 3030 locally and uses PostgreSQL via Supabase for data persistence.

Design System (apps/design-system)

Interactive component documentation and design resource hub:

• Component registry: References UI components from packages/ui and packages/ui-patterns
• Live examples: Interactive component previews with source code
• Documentation: MDX-based guides for each component
• Themes: Multiple theme configurations with dark mode support
• Content: Contentlayer2 for MDX processing with hot reload

Runs on port 3003 and uses Contentlayer2 for content management. The registry is auto-generated from component definitions and must be rebuilt after adding new components.

Architecture Overview

Loading diagram...

Development Workflow

All apps use pnpm workspaces for dependency management and Turbo for build orchestration. Each app can be developed independently:

• pnpm dev:www – Start marketing website
• pnpm dev:docs – Start documentation site
• pnpm dev:cms – Start CMS
• pnpm dev:design-system – Start design system

Content is typically sourced from Payload CMS and rendered across the www and docs applications. The design system serves as a reference for UI consistency across all properties.

Backend Infrastructure & Edge Functions

Overview

The backend infrastructure is built on Supabase, a PostgreSQL-based backend-as-a-service platform. It provides database management, authentication, storage, and serverless edge functions. The system uses Deno-based edge functions for compute-intensive tasks like semantic search and dynamic image generation.

Loading diagram...

Database Architecture

The PostgreSQL database is organized into multiple schemas:

• public schema: Core content tables (page, page_section) with vector embeddings for semantic search
• content schema: Error codes and service definitions for API documentation
• storage schema: File storage configuration (fonts, assets)
• graphql_public schema: GraphQL API exposure

Key tables include:

• page: Stores documentation pages with metadata and full-text search tokens
• page_section: Contains page sections with embeddings (1536-dimensional vectors from OpenAI)
• feedback: User feedback on documentation pages
• content.error: Error codes mapped to services (AUTH, REALTIME, STORAGE)

Edge Functions

Search Embeddings Function

Located at supabase/functions/search-embeddings/index.ts, this function powers semantic search:

1. Input: User query string
2. Processing:
   • Content moderation via OpenAI API
   • Query embedding generation using text-embedding-ada-002
   • Vector similarity search against page sections
3. Output: Ranked list of matching documentation sections

The function supports two search indices: standard and alternate (Nimbus). It uses a match threshold of 0.78 for similarity filtering.

OG Images Function

Located at supabase/functions/og-images/, this function generates dynamic Open Graph images for social sharing:

• Renders React components to PNG images
• Supports multiple templates: Docs, Events, Customer Stories
• Loads custom fonts from Supabase Storage
• Accepts query parameters for customization (title, icon, type, etc.)

Configuration

The supabase/config.toml file defines:

• API: Exposed schemas, max row limits (1000), CORS headers
• Database: PostgreSQL 15, local port 54322
• Auth: JWT expiry (1 hour), email confirmation settings
• Storage: 50MiB file size limit, public fonts bucket
• Functions: JWT verification disabled for search-embeddings (public access)

Search Implementation

The system uses hybrid search combining full-text search (FTS) and semantic search via reciprocal rank fusion (RRF):

• Full-text search ranks by title relevance (10x weight) and content relevance
• Semantic search uses pgvector dot product similarity
• Results merged using RRF algorithm with configurable weights
• Supports filtering by match threshold and result count

Error Handling

Edge functions implement a two-tier error system:

• UserError: Client-facing errors (400 status) with detailed messages
• ApplicationError: Server errors (500 status) with logging for debugging

CORS headers are included in all responses to support cross-origin requests.

Development Workflow & Build System

Monorepo Architecture

This repository uses Turborepo to manage a monorepo containing multiple applications and shared packages. The workspace is organized into four main directories:

• /apps – Main applications (www, studio, docs, cms, design-system, ui-library)
• /packages – Shared libraries and utilities (ui, common, config, tsconfig, etc.)
• /blocks – Reusable component blocks
• /e2e – End-to-end tests

Package Management

The project uses pnpm (v10.24+) as the package manager with workspace support. Key commands:

pnpm install          # Install all dependencies
pnpm add <pkg>        # Add package to current workspace
cd apps/studio && pnpm add react  # Add to specific workspace

The pnpm-workspace.yaml file defines workspace packages and maintains a shared dependency catalog to ensure consistent versions across all apps.

Build System with Turbo

Turbo orchestrates builds across the monorepo with intelligent caching and parallel execution. Key build commands:

pnpm build            # Build all apps
pnpm build:studio     # Build studio only
pnpm build:docs       # Build docs only
pnpm build:cms        # Build cms only

Each app has specific environment variables defined in turbo.json that are required during builds. The build system respects dependency graphs, ensuring packages are built before dependent apps.

Local Development

Start all applications in development mode:

pnpm dev              # Start all apps in parallel
pnpm dev:studio       # Start studio only
pnpm dev:docs         # Start docs only
pnpm dev:www          # Start www only

Development servers run on:

• www – http://localhost:3000
• studio – http://localhost:8082 (requires Docker)
• docs – http://localhost:3001/docs

Docker Setup for Studio

Studio requires a complete Supabase backend running in Docker. Setup process:

cd docker
cp .env.example .env
docker compose up

This starts 15+ services including PostgreSQL, Kong API Gateway, Auth, REST API, Realtime, Storage, and Analytics. The docker-compose.yml file orchestrates all services with health checks and proper dependency ordering.

Environment Configuration

Local environment setup uses the generateLocalEnv.js script:

pnpm setup:cli        # Start Supabase CLI and generate .env files

This script:

1. Starts the Supabase backend
2. Extracts API keys and credentials
3. Generates .env.test for studio
4. Generates .env.local for e2e tests

Testing & Quality

pnpm lint             # Run ESLint across all packages
pnpm typecheck        # TypeScript type checking
pnpm test:studio      # Run studio tests
pnpm test:ui          # Run UI package tests
pnpm e2e              # Run end-to-end tests
pnpm format           # Format code with Prettier

Common Development Tasks

Add a package to a specific workspace:

cd apps/studio
pnpm add react-query

Run a single app with full backend:

pnpm setup:cli
pnpm dev:studio-local

Clean build artifacts:

pnpm clean            # Remove all build outputs and node_modules

Troubleshooting

• Port conflicts: Ensure ports 3000, 3001, 8082, and 8000 are available
• Docker issues: Run docker compose down -v to reset volumes
• Dependency conflicts: Run pnpm install to sync lock file
• Build failures: Check turbo.json for required environment variables

Testing, Quality Assurance & CI/CD

Unit Testing

The repository uses Vitest for unit testing across packages and applications. Each package has its own vitest.config.ts configuration.

Key configurations:

• UI Package (packages/ui): Tests run in jsdom environment with coverage reporting (LCOV format)
• Studio App (apps/studio): Tests run in jsdom with React plugin support, path aliases, and setup files for polyfills and Radix UI

Running unit tests locally:

pnpm run test:ui              # Test UI package
pnpm run test:studio          # Test Studio app
pnpm run test:studio:watch    # Watch mode for Studio

Coverage reports are generated in LCOV format and uploaded to Coveralls for tracking.

End-to-End Testing

Playwright powers the E2E test suite in e2e/studio, covering critical user workflows across the Studio dashboard.

Test organization:

• Feature-based test files: features/*.spec.ts (database, auth, storage, SQL editor, etc.)
• Setup file: _global.setup.ts for authentication and environment initialization
• Utilities: Helper functions for common operations (auth, storage, dismissing toasts)

Configuration highlights:

• Parallel execution: 3 workers for self-hosted, 1 worker for platform (API rate limits)
• Retries: 5 retries in CI, 0 locally
• Timeouts: 120s per test, 20s for assertions, 15 minutes for platform setup
• Artifacts: Videos and traces retained on failure, HTML reports generated

Running E2E tests:

cd e2e/studio
pnpm exec playwright install    # Install browsers first
pnpm run e2e                     # Run all tests
pnpm run e2e -- --ui            # Interactive UI mode
PWDEBUG=1 pnpm run e2e -- --ui  # Debug mode

Environment setup requires .env.local configuration with STUDIO_URL, IS_PLATFORM, and authentication credentials.

Code Quality & Linting

Pre-commit checks ensure code consistency:

pnpm run test:prettier    # Check formatting with Prettier
pnpm run format           # Auto-format code
pnpm run typecheck        # TypeScript type checking
pnpm run lint             # ESLint checks

CI/CD Pipeline

GitHub Actions orchestrates automated testing and quality checks on every PR and push:

Loading diagram...

Key workflows:

• studio-unit-tests.yml: Runs on Studio changes; uploads coverage to Coveralls
• ui-tests.yml: Runs on UI package changes; parallel coverage tracking
• studio-e2e-test.yml: Runs E2E tests; uploads Playwright artifacts; comments results on PR
• prettier.yml: Validates code formatting across apps, packages, and i18n
• typecheck.yml: TypeScript and ESLint checks on all code

CI optimizations:

• Sparse checkout to reduce clone time
• pnpm caching for faster dependency installation
• Concurrency groups to cancel outdated runs
• Blacksmith runners (4vCPU) for faster builds
• Memory optimization: NODE_OPTIONS=--max-old-space-size=3072 for tests

Pre-Flight Checks for Contributors

Before submitting a PR, run locally:

pnpm run build              # Ensure code builds
pnpm run test:prettier      # Check formatting
pnpm run typecheck          # Verify types
pnpm run lint               # Run linters

This reduces CI feedback cycles and catches issues early.