Miranda Limonczenko
36371de151
Part 3 of 3. Stack: #50742 → #50744 → #50743. Review #50742 and #50744 first. Closes DOCS-1177 ## Problem `CONTRIBUTING.md` mixed how to write a page with how the repo is laid out. That's why it reached 568 lines, and why a contributor looking for either half reads past the other. #50742 gives the writing half its own home. ## Solution Trim `CONTRIBUTING.md` to repo mechanics, 568 lines down to 163. **Removed**, now in the style guide: general principles, information types, document types, components and elements, styling and grammar, word usage. **Kept**: the skills table, repo organization, guide and reference structure, content reuse, search. Content listings keeps its data file, ID rules, and test command here; the when-to-use-one part is in the style guide. **Added**: a table linking each style guide file. Wire the contributor-facing entry points at the guide: - `apps/docs/AGENTS.md` — gains a style guide section listing each file separately, so an agent can load one file without the others. This auto-loads for anything under `apps/docs`, making it the highest-leverage pointer in the repo. - Root `AGENTS.md` — claimed the skills are "the source of truth for conventions." For docs content style that's now the guide, with the skills as the process that applies it. - `.github/pull_request_template.md`, `.coderabbit.yaml`, `apps/docs/README.md`, `apps/docs/DEVELOPERS.md` — updated paths. Drop the `.prettierignore` exemption for `apps/docs/CONTRIBUTING.md`. It's short enough to format now, and a repo that publishes a style guide shouldn't exempt its own contributing doc. ## Notes for review Discoverability in a markdown-only guide is entirely these pointers, so they're the load-bearing part of this PR rather than cleanup. Both surviving anchor links into `CONTRIBUTING.md` target `#ai-agent-skills-for-docs-authoring`, which is kept. No dangling anchors. This PR sits last in the stack on purpose. It deletes the style sections that seven skill instructions referenced, so it has to land after #50744 rewires them. ## Manual testing 1. Open `apps/docs/CONTRIBUTING.md` and confirm every remaining section is repo mechanics, and the style guide table links resolve. 2. Confirm `apps/docs/AGENTS.md` names each style guide file, in size order: `WORD_LIST`, `01-voice-and-tone`, `02-elements`, `03-page-structure`. 3. Run `grep -rn "apps/docs/WORD_LIST" --include="*.md" --include="*.yaml" . | grep -v node_modules` and confirm only the intentional stub matches. 4. Run `npx prettier --config prettier.config.mjs --check apps/docs/CONTRIBUTING.md`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated contributor guidance to distinguish writing conventions from repository mechanics, with the style guide as the reference for documentation style. * Added style guide links and clarified when to use the writing and editing skills. * Revised the docs contribution guide with a style guide file list and steps for adding content listings. * Updated the pull request checklist to direct contributors to the documentation skills for style guidance. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
6.7 KiB
Supabase Monorepo
pnpm 11 + Turborepo monorepo. Requires Node >= 22.13.
Structure
| Directory | Purpose |
|---|---|
apps/studio |
Supabase Studio/Dashboard — has its own apps/studio/AGENTS.md (see below) |
apps/docs |
Documentation site — Next.js app router, MDX (port 3001, served under /docs) — has its own apps/docs/AGENTS.md |
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 |
apps/kb |
Knowledge base — Astro — has its own apps/kb/AGENTS.md |
apps/learn |
Courses site — Next.js + Contentlayer (port 3007), early stage |
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
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 dev:kb # run knowledge base 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, apps/docs/content/_partials/access-control/scoped_pat_*.mdx (run make -C apps/docs/spec generate.partials.access-control).
Conventions
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.
Public surfaces — this repo is public: PR descriptions, issues, and code comments are world-readable. Keep internal content out of them: absolute production metrics (event counts, user counts, revenue figures: state percentages, ratios, or relative change instead), internal decision detail (vendor, legal, pricing, or strategy discussions), and competitor names (protocol identifiers such as user-agent strings are fine). Put that context in the Linear issue and link it.
Skills
The skills in .agents/skills/ are the source of truth for conventions. Load the relevant ones before working, don't guess. One exception: for docs content style, apps/docs/style-guide/ is the source of truth and the docs skills are the process that applies it.
copywriting— any user-facing text, anywhere in the monorepopm-the-docs/write-the-docs/edit-the-docs/ask-the-docs/review-the-docs— anything underapps/docs(seeapps/docs/CONTRIBUTING.mdfor the authoring skill model, andapps/docs/style-guide/for the content style rules they apply)telemetry-standards— PostHog events,packages/common/telemetry-constants.tsdev-toolbar-review—packages/dev-tools,packages/common/posthog-client.ts,packages/common/feature-flags.tsxsafe-sql-execution— any code that builds or executes SQL against user databasesreact-hook-form— writing or modifying any form code, anywhere in the monorepovitest/vercel-composition-patterns— generic unit-testing and React composition references
Studio
Before working on anything in apps/studio, read apps/studio/AGENTS.md if it isn't already in context — it maps Studio tasks to required skills and covers the TanStack Start migration rules.