better-supabase sits on the supabase-js client you already use. You keep your database, your RLS policies, Supabase Auth and Storage. The CLI reads your schema and generates a typed repository for every table, so a query is a typed object instead of a string.
Before and after
With supabase-js, the query is a string and the error is a Postgres code:
Each call is still one PostgREST request, and it runs as the signed-in user, so your RLS policies decide what it can read and write. The supabase-js migration guide maps every supabase-js call to its repository equivalent.
Install and quick start
pnpm add better-supabase @supabase/supabase-js
pnpm add -D pg @supabase/[email protected]
supabase start
pnpm better-supabase init # config, src/lib/supabase and framework glue
pnpm better-supabase gen # database.types.ts, generated.ts and the data hooks
pg and @supabase/postgrest-typegen are optional peers that only the CLI loads. The package is ESM only. The CLI needs Node 24 or later, and the runtime entries run on every WinterTC runtime.
On the server, the adapter gives each request a db for the caller. In the browser, bsb.db is the same client for the current session:
pnpm better-supabase init # config, client and framework glue
pnpm better-supabase gen # types and data hooks
pnpm better-supabase gen --check # exit 1 in CI when the schema drifted
pnpm better-supabase add queue # a block's SQL into supabase/schemas
pnpm better-supabase doctor # RLS, grants, indexes and Supabase advisors
pnpm better-supabase skills install # Agent Skills for your coding agent
A block is a feature most apps build by hand. better-supabase add installs its SQL, and the app calls the instance on db. The catalog is grouped by what the block is for:
The package ships Agent Skills for queries, APIs, auth and tests:
npx skills add ScaleDockHQ/better-supabase
The docs are also available as /llms.txt, as Markdown at /docs/<page>.md, and through the read-only docs MCP server at https://bettersupabase.com/mcp. See For AI agents.
Setup, the local stack, scripts and the release process are in CONTRIBUTING.md. The invariants and the "when you change X, also update Y" table for anyone changing the code, human or agent, are in AGENTS.md. Every user-visible change needs a changeset.
Repository
packages/better-supabase/ the library, its CLI and the consumer skills
apps/docs/ the documentation site
apps/examples/ one app per adapter
supabase/ the local stack and the fixture schema
pnpm verify is the gate before a push. The apps are served with pnpm dev:portless.
Security
Report vulnerabilities privately; see SECURITY.md.