TypeScript 14,874 FILES 10 FINDINGS

HOW SUPABASE
ACTUALLY WORKS

The open-source Firebase alternative. Conventions, patterns, and architecture extracted from the supabase/supabase repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Data: React Query

WHAT_MATTERS

→
This is a monorepo — check workspace dependencies before modifying shared code
→
packages/ui/src/lib/utils/cn.ts is a hub file (imported by 57 files) — changes here ripple everywhere
→
Circular import chains detected — avoid adding to these cycles

KEY_FINDINGS

Local Supabase setup detected (supabase/ directory). Use `supabase db push` for migrations, not the dashboard.

HIGH

This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.

HIGH

Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern -- don't create a separate test/ directory.

HIGH

Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.

HIGH

14 barrel export files found

Project strongly prefers named exports over default exports. Use `export function` / `export const`, not `export default`.

HIGH

53 named vs 6 default exports in sampled files

Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.

HIGH

15 files

Hub files (most depended on): packages/ui/src/lib/utils/cn.ts (imported by 57 files); packages/pg-meta/src/pg-format/index.ts (imported by 40 files); packages/icons/src/createSupabaseIcon.ts (imported by 34 files); apps/studio/data/storage/keys.ts (imported by 24 files); packages/marketing/src/go/schemas.ts (imported by 23 files). Changes here have the widest blast radius.

HIGH

Circular import chains detected: useCommandMenuTelemetry.ts → useCommandMenuTelemetryContext.tsx; Day5.tsx → index.tsx; CustomersSliderMobile.tsx → index.tsx. Avoid adding to these cycles.

HIGH

smart_toy USING_AI_TOOLS

→check file importance before editing hub files
→follow existing patterns listed in quick reference

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Commands

- **Dev:** `turbo run dev --parallel`
- **Build:** `turbo run build`
- **Lint:** `turbo run lint`
- **typecheck:** `turbo --continue typecheck`
- **generate:types:** `supabase gen types typescript --local > ./supabase/functions/common/database-types.ts`
- **authorize-vercel-deploys:** `tsx scripts/authorizeVercelDeploys.ts`

## Critical Constraints

- **Testing:** Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern -- don't create a separate test/ directory.
- **Core modules:** Hub files (most depended on): packages/ui/src/lib/utils/cn.ts (imported by 57 files); packages/pg-meta/src/pg-format/index.ts (imported by 40 files); packages/icons/src/createSupabaseIcon.ts (imported by 34 files); apps/studio/data/storage/keys.ts (imported by 24 files); packages/marketing/src/go/schemas.ts (imported by 23 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular import chains detected: useCommandMenuTelemetry.ts → useCommandMenuTelemetryContext.tsx; Day5.tsx → index.tsx; CustomersSliderMobile.tsx → index.tsx. Avoid adding to these cycles.

## Stack

Next.js, Expo, Supabase, Tailwind CSS, TypeScript

## Project Structure

- `supabase/` — Supabase configuration and migrations
- `scripts/` — Build / utility scripts
- `e2e/` — End-to-end tests

## Core Modules (by structural importance)

- `packages/ui/src/lib/utils/cn.ts`
- `packages/ui/src/components/Icon/IconBase.tsx`
- `packages/icons/src/createSupabaseIcon.ts`
- `packages/pg-meta/src/pg-format/index.ts`
- `packages/icons/src/defaultAttributes.ts`

## Conventions & Patterns

- **Supabase:** Local Supabase setup detected (supabase/ directory). Use `supabase db push` for migrations, not the dashboard.
- **Project structure:** This is a monorepo. Changes may affect multiple packages. Check workspace dependencies before modifying shared code.
- **Import conventions:** Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.
- **Export conventions:** Project strongly prefers named exports over default exports. Use `export function` / `export const`, not `export default`.
- **Dominant patterns:** Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

RELATED_REPOS

NEXT.JS CAL.COM

HOW SUPABASEACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

RELATED_REPOS

HOW SUPABASE
ACTUALLY WORKS