Operations
Local Supabase startup, sync, reset, seeds, storage, and generated types.
The local Supabase stack backs the SaaS and API apps during development.
pnpm supabase:start
pnpm supabase:syncThe sync task pushes pending migrations and seeds to the local database (falling back to a full reset when the push fails) and then seeds the Storage buckets. OAuth-related warnings about missing Google credentials are safe unless you are testing OAuth.
supabase/config.toml turns on the Supabase CLI stack engine with [experimental] stack = true. It needs CLI 2.121.0 or later, which the pnpm catalog pins.
pnpm supabase:start writes the URLs and keys to .env.development.local, and scripts read them from supabase status --output-format json through @workspace/foundation/local-supabase.pnpm supabase:start there. Checking out another branch in the same directory starts a separate, empty project.pnpm supabase:start passes --runtime native, which runs every service as a plain process without a container engine, the same as CI. A project keeps the runtime it was created with, so for a project created earlier on Docker the script falls back to --runtime auto and stays on Docker until you destroy it.pnpm exec supabase stack list lists every local project on the machine. pnpm supabase:stop stops this one and keeps its data, and pnpm --filter @workspace/supabase-runtime supabase:destroy deletes it.start and status have no -o flag. Use --output-format json or --env. supabase stop --no-backup is replaced by supabase stack destroy.content_path, so the confirmation template lives under [remotes.main] and [remotes.develop]. Local confirmation emails use the default link, which /auth/confirm accepts as a PKCE code.Stack projects keep their data apart from the previous engine. After switching, stop the old containers with SUPABASE_EXPERIMENTAL_STACK=0 pnpm exec supabase stop, then run pnpm supabase:start and pnpm supabase:sync.
Use reset only when a clean local database is intended:
pnpm supabase:resetAfter reset, browser sessions from the previous local auth database are stale. Sign in again with the seeded test account.
test@example.comPassword123!tractor-service, auto-garage, bike-scooter-shop, equestrian-centertest@example.com is also the seeded system admin. All seeded users share the same password. Local development lists every persona, including the portal-only customers test3@example.com, test4@example.com and test5@example.com and the role-specific accounts such as owner@example.com, crm.editor@example.com and viewer@example.com.
Seed files provide deterministic coverage for every shop organization: customers, contacts, roles, teams, products, inventory, customer assets, tasks, agenda items, quotes, invoices, orders, files, inbox threads, AI chat history, notifications, employees, time, expenses, hiring, workflows, webhooks, audit logs and billing read models. Files 100 to 170 in supabase/seeds/ hold the demo data, one domain per file, and each starts with a -- Covers: comment. docs/agents/supabase-schema.md describes the id scheme and the conventions for adding rows.
Storage buckets are configured through supabase/config.toml and seeded from supabase/seed-buckets/. Bucket ids match product features: users, customers, organization, assets, products, files, knowledge, ai, integrations, audit-logs, and workflows. The reset flow recreates those local buckets and loads public seed objects from the matching folders. Object paths are UUID-first ({orgId|userId}/…); never use org slugs as the tenant folder.
On a hosted project, create the eleven new buckets and delete the old ids after deploy. Existing hosted objects are discarded for this cutover; path columns 404 until objects are re-uploaded or the remote database is reset.
Run pnpm supabase:types after schema changes. It runs better-supabase gen against the local database with better-supabase.config.ts and writes the schema and database types to packages/supabase-runtime/src/generated/. The config lists both public and graphql_public, so the types keep the GraphQL definitions. CI runs better-supabase gen --check and fails when the committed files are out of date.
Last updated on