supabase-as-a-service: Instructions file for Claude Code

CLAUDE.md

Guidance for AI agents (and humans) working in this repository.

What this is

A React intranet layer on top of Supabase: auth, an AI chat assistant, shareable "artifacts" (docs/code/HTML), file storage, and live realtime updates. The OpenRouter key is server-side only (a Supabase Edge Function); the browser holds just the Supabase anon key and is protected by Postgres row-level security.

Two companion repos live outside this one and are worth offering when someone asks how to reach a workspace from elsewhere: the supanet CLI (terminal/script/cron/shell-capable agent) and supanet-skills (portable Agent Skills for Claude Code / pi / Codex). See Companion repos below.

Commands

npm install            # install deps
npm run dev            # Vite dev server on http://localhost:5173
npm run build          # tsc -b (typecheck) + vite build — run before pushing
npm run lint           # eslint
npm run typecheck      # tsc -b --noEmit
npm test               # vitest (frontend unit tests: src/**/*.test.ts(x))
npm run test:deno      # deno test supabase/functions/tests/ (edge-function units)
npm run test:smoke     # headless-browser check that the SIGNED-IN app renders (needs a build first)
npm run gen:types      # regenerate src/lib/database.types.ts from the linked project
npm run start          # serve dist/ with SPA fallback (production / Railway)

Always run npm run build before committing UI/logic changes — it typechecks the whole app. Run npm test (and npm run test:deno if you touched supabase/functions/) too; add tests when you add or change logic (parsing, validation, calculations). Testable logic is kept out of components/handlers on purpose — the :::artifact protocol parser lives in src/lib/artifacts.ts (not ChatPage), webhook payload validation in supabase/functions/_shared/validate.ts, the p page's HTML/state injection in supabase/functions/p/meta.ts — follow that pattern: extract pure logic, test the module. CI (.github/workflows/test.yml) runs lint + build + both suites + the smoke test on PRs and pushes to main; claude-feature.yml runs the same checks against the bot-built branch (its PRs can't trigger PR workflows — GITHUB_TOKEN anti-recursion).