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.

| 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/<name> | | APIs (OpenAPI, AsyncAPI, Arazzo) | better-supabase/spec | | AI SDK, Chat SDK, eve, flags, workflows | Integrations | | Authorization library adapters | better-supabase/claims and better-supabase/contract | | 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