Overview

A block is a feature most SaaS apps build by hand: organizations and invitations, background jobs, notifications, outgoing webhooks, plan entitlements. Each block installs one or more SQL modules into supabase/schemas with better-supabase sql add, and blocks with a TypeScript side import it from better-supabase/blocks/<name>. Blocks that are SQL only have no subpath; you call their functions from policies and RPCs.

pnpm better-supabase sql add organizations invitations

import { createOrganizations } from "better-supabase/blocks/organizations";

To build several blocks with one set of options, and wire the blocks that use each other, use createBlocks from better-supabase/blocks.

A block can be extended without forking it: add your own columns and type them with a Standard Schema, steer its methods with hooks in TypeScript or SQL, wrap its transport with middleware and add methods. See Extending blocks.

List the modules to keep in sync in sql.modules in better-supabase.config.ts, keyed by module name, with each module's settings as the value. The primitives that every app uses, such as list queries, storage and realtime topics, are not blocks and keep their top-level subpaths.

ConnectionsCopy Anchor Link

A block's TypeScript side runs its SQL functions through a connection you pass in. It never opens a pool of its own.

Every function that takes a SQL client accepts @supabase/server's Postgres clients as they are, so an app that already composes withPostgresClient and withPostgresAdminClient keeps one pool and one connection string (SUPABASE_DB_URL by default, or connectionString). withBlock from better-supabase/server builds a block on the pipeline context; see middleware.

@supabase/server runs each query in its own transaction. A block call is one SQL function, so that changes nothing for the blocks, but outbox.emit() then commits on its own instead of with the writes before it. Emit from SQL (emit_event inside the function that writes) when the event must commit with the write.

A SQL connection needs TCP: Node, Deno, Bun and the Supabase Edge runtime have it, Cloudflare Workers and other isolates without sockets do not. There, use rpcTransport for the blocks that call only SQL functions (organizations, notifications, outgoing webhooks, flags, announcements and the rest of the blocks that take a transport, and createOutbox, which takes a transport in place of the SQL client), and the pgmq_public RPCs for jobs. The TypeScript helpers of the idempotency keys, the webhook inbox, incoming webhooks, route rate limits and exportAuditLog still need a SQL connection, but every function a module grants, the service-role ones of jobs, idempotency, webhook-inbox and access included, gets an entry point in the API schema, so a server can call them over the Data API. Give the module an API schema (sql.modules.<module>.api, see SQL modules), expose that schema, and pass it as rpcTransport(supabase, { schema: "api" }). Never expose the module schema itself.

BlocksCopy Anchor Link

SDK adaptersCopy Anchor Link

An adapter connects a third-party SDK to the blocks above. It owns no tables and no SQL modules of its own: install the modules of the blocks it uses.

How modules work togetherCopy Anchor Link

sql add installs a module with the modules it requires. The modules it works with are optional: when one of them is installed too, the module calls it (it queues a job, sends a notification, checks a plan), and without it the module installs and runs without that step. Every module also writes its events to the outbox when the outbox is installed. better-supabase sql list prints both lists for each module.

The other SQL modules (updated-at, actor, rate-limit, support-sessions and the rest) are listed on the SQL modules page. The roadmap lists what comes next.