better-supabase
GitHubGet started
Open source. MIT. Built on the official Supabase packages.

The typed layer for Supabase apps, APIs, MCP servers and jobs.

Generated models, a typed repository that returns results instead of throwing, auth glue that skips needless network calls, and adapters for Next.js, Hono, oRPC and Edge Functions.

Get startedGitHub
npm
app/customers/page.tsx
import { bs } from '@/lib/supabase/server';

export default async function Customers() {
  const { db } = await bs.context();

  const result = await db.customers.findMany({
    select: ['id', 'name'],
    where: { status: 'active', notes: { some: { kind: 'call' } } },
    include: { organization: { select: ['name'] } },
    orderBy: { name: 'asc' },
    limit: 20,
  });
  // { id: string; name: string; organization: { name: string } }[]

  if (!result.ok) return <ErrorState error={result.error} />;
  return <CustomerList customers={result.data} />;
}

What you get

The glue code every Supabase app rewrites, done once

Auth wiring, typed repositories, pagination, includes, nested filters, soft delete, timestamps, upserts, cache invalidation, list pages, storage paths and realtime topics.

Stronger generated typesgen wraps supabase gen types and adds relationship cardinality, unique keys, CHECK-constraint unions, typed jsonb and camelCase column maps.A typed repositoryfindMany with where, include, orderBy and pagination compiles to one PostgREST request, or to SQL on the direct-Postgres path.Results, not exceptionsEvery call returns a Result with a plain, serializable DbError. Return it from server actions and RPC handlers; .orThrow() is opt-in.Your casing, everywhereKeep database names with casing: 'snake', or get camelCase rows renamed inside the PostgREST query itself.Auth without extra round tripsValid access tokens never touch the Auth server. Refresh happens once, in the proxy, and is single-flighted.Cache tags that follow writesMutations invalidate bs:<table> and bs:<table>:<id>, with read-your-writes inside Next.js server actions.PluginsTimestamps, soft delete, tenants, actors, validation and rules, each versioned and opt-in.BlocksList pages, storage paths, realtime topics, background jobs and SQL modules you can sync into migrations.

Frameworks

Works where your code runs

Adapters build a per-request client for the caller, so the same repository API works in pages, routes, procedures and functions.

Next.jsProxy, Server Components, route handlers, server actions and cache tags.HonoMiddleware, Result-aware handlers and REST resources that match your OpenAPI document.oRPCA middleware that adds the caller’s repositories to the oRPC context.Edge FunctionsFetch handlers for Supabase Edge Functions, Deno, Bun and Workers.MCPTools from your tables and your own code, running as the signed-in user.React and TanStack QueryTyped query and mutation options for every table, with table-based invalidation.

CLI

Codegen and diagnostics in one command line

One binary for the whole loop: set up a project, generate types from your local stack, and catch security and performance problems before they ship.

terminal
pnpm better-supabase init     # config, client and framework glue
pnpm better-supabase gen      # database.types.ts + generated.ts
pnpm better-supabase gen --check  # fail CI on schema drift
pnpm better-supabase doctor   # RLS, indexes and Supabase advisors
  • gen --check fails CI when the database and generated types drift apart.
  • doctor checks RLS, indexes, auth config and env files, and runs the Supabase Security and Performance Advisors locally.
  • Reports as text, JSON, SARIF or GitHub annotations.
CLI reference

Runs on every WinterTC runtime

Runtime entries import no Node built-ins, and the core has no dependencies beyond the Supabase packages and Standard Schema.

  • Node.js
  • Deno
  • Bun
  • Cloudflare Workers
  • Vercel Functions
  • Supabase Edge Functions

Get started

From install to typed queries in four steps

  1. 01Installpnpm add better-supabase @supabase/supabase-js
  2. 02Initbetter-supabase init writes the config, the client and framework glue.
  3. 03Generatebetter-supabase gen reads your local stack and writes typed models.
  4. 04Queryconnect() per request with the user’s client, so RLS always applies.

FAQ

Questions

Stop rewriting the glue code every Supabase app needs

Start with one table and one query. Keep supabase-js for everything else.

Read the quickstartStar on GitHub