Better Supabase

Typed repositories, auth glue and a CLI for Supabase apps, APIs, MCP servers and jobs.

npm license

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.

Where you run	Docs
Next.js, Hono, oRPC, Expo Router, SvelteKit, TanStack Start, React Router	Frameworks
Edge Functions, Node, NestJS, Astro, SolidStart, H3, Nuxt, Elysia	Frameworks
React, React Native, Vue, Solid, Svelte	Frontend
PowerSync and SQLite on the device	Local data
MCP servers	MCP

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:

Category	Catalog
Organizations and identity	Organizations
Database	Database
Collaboration	Collaboration
Work	Work
CRM	CRM
Commerce	Commerce
Content	Content
AI	AI
Automation	Automation
Developer	Developer
Growth	Growth
People and scheduling	People

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.

Area	Start here
Repositories, results and config	better-supabase
Server, Postgres and auth	better-supabase/server
Framework adapters	better-supabase/next
Browser client and data hooks	better-supabase/client
Blocks	better-supabase/blocks/
APIs (OpenAPI, AsyncAPI, Arazzo)	better-supabase/spec
AI SDK, Chat SDK, eve, flags, workflows	Integrations
Tests	better-supabase/testing

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.