better-supabase
Typed repositories, auth glue and a CLI for Supabase apps, APIs, MCP servers and jobs.
Docs · Quickstart · Blocks · Examples · Changelog · GitHub
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:
const { data, error } = await supabase
.from("customers")
.select("id, name")
.eq("status", "active")
.limit(20);
if (error) throw error;
With better-supabase, the same read is a typed call on db, and the generated hook takes the same arguments:
const customers = await db.customers
.list({ select: ["id", "name"], where: { status: "active" }, limit: 20 })
.orThrow();
const rows = useCustomers({
select: ["id", "name"],
where: { status: "active" },
limit: 20,
});
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:
const { db } = await bsb.context();
const customers = await db.customers
.list({ where: { status: "active" }, limit: 20 })
.orThrow();
gen.hooks writes useCustomers and useCustomer next to the generated module. Data hooks covers the options.
Use it where you run
An adapter verifies the session, refreshes it in the proxy and gives each handler a db for the caller.
The CLI
One command per job. bsb is the short name.
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
The CLI reference lists every command and flag.
Blocks and presets
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:
A preset installs a set of blocks for a product, such as a CRM, a helpdesk or a CMS.
Subpaths
Each feature is its own entry, so an app only loads what it imports.
For AI agents
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.
Documentation
The full documentation is at bettersupabase.com/docs.
License
MIT © 2026 ScaleDock
Contributing
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.