# better-supabase

> A strongly typed layer over Supabase for apps, APIs, MCP servers and jobs.

better-supabase is a TypeScript library for Supabase: typed repositories
compiled to PostgREST, auth for every caller, framework adapters, blocks
(SQL modules with typed APIs) and a CLI for codegen and doctor checks.

Every page below is Markdown. Add `.md` to a page URL, or send
`Accept: text/markdown`, to read any other page the same way.

- [Introduction](https://bettersupabase.com/docs.md): A strongly typed layer over Supabase for apps, APIs, MCP servers and jobs.

## Getting started

- [Quickstart](https://bettersupabase.com/docs/getting-started.md): Install better-supabase, generate your schema and run your first typed query.
- [Peers](https://bettersupabase.com/docs/getting-started/peers.md): The optional peer dependencies of better-supabase, the version ranges they accept and the subpaths that need each one.

## Guides

- Concepts
  - [Schema and codegen](https://bettersupabase.com/docs/concepts.md): What better-supabase generates on top of supabase gen types, and why.
  - [Casing](https://bettersupabase.com/docs/concepts/casing.md): snake_case or camelCase models, mapped at the edge of the database.
  - [Results and errors](https://bettersupabase.com/docs/concepts/results.md): Every call returns a Result with a typed, serializable DbError.
  - [better-result](https://bettersupabase.com/docs/concepts/better-result.md): Return better-result values from repositories with withBetterResult, or convert single results at the boundary.
  - [Caching](https://bettersupabase.com/docs/concepts/caching.md): How reads know which tables they touched, and how writes invalidate exactly those reads.
  - [Temporal](https://bettersupabase.com/docs/concepts/temporal.md): Instants, durations and the clock as Temporal values, and the polyfill for runtimes without it.
  - [Naming](https://bettersupabase.com/docs/concepts/naming.md): The names better-supabase uses for definitions, instances, files and types, and the renames from earlier versions.
- Repository
  - [Repository](https://bettersupabase.com/docs/repository.md): A typed repository per table, compiled to one PostgREST request.
  - [Filtering](https://bettersupabase.com/docs/repository/filtering.md): Column operators, AND/OR/NOT, and filters through relations.
  - [Includes](https://bettersupabase.com/docs/repository/includes.md): Load related rows in the same request, typed by relation cardinality.
  - [Aggregates](https://bettersupabase.com/docs/repository/aggregates.md): Sums, averages, minimums, maximums and grouped counts in one request, without loading rows.
  - [Read sets and $many](https://bettersupabase.com/docs/repository/read-sets.md): Run several reads as one round trip, a single GET to a stable function or one SQL transaction.
  - [Pagination](https://bettersupabase.com/docs/repository/pagination.md): Page numbers or offset windows with totals, or keyset cursors for infinite lists.
  - [Writing](https://bettersupabase.com/docs/repository/writing.md): create, update, upsert and delete, with typed conflicts and optimistic concurrency.
  - [Unique keys and errors](https://bettersupabase.com/docs/repository/unique-and-errors.md): findUnique by any unique key, typed constraint names, and narrowing database errors.
  - [PowerSync](https://bettersupabase.com/docs/repository/powersync.md): The same repositories over a PowerSync SQLite database on the device.
  - [expo-sqlite](https://bettersupabase.com/docs/repository/expo-sqlite.md): The same repositories over a local expo-sqlite database, without PowerSync.
- Auth and server
  - [Overview](https://bettersupabase.com/docs/auth.md): One resolver for every caller, local verification, and refreshes only where they belong.
  - [Environment](https://bettersupabase.com/docs/auth/env.md): Validated Supabase settings, with every framework spelling and no leaked values.
  - [Session cookies](https://bettersupabase.com/docs/auth/sessions.md): Read and write the @supabase/ssr cookie format from any framework.
  - [MFA and SSO](https://bettersupabase.com/docs/auth/mfa-sso.md): Require a second factor on routes, actions, pages and RLS policies, and scope SSO users to their tenant.
  - [OAuth consent and connected agents](https://bettersupabase.com/docs/auth/oauth-consent.md): Serve the consent page for the Supabase Auth OAuth server from your app, and let users see and disconnect the agents they approved.
  - [Account deletion](https://bettersupabase.com/docs/auth/account-deletion.md): Delete or suspend a user, end their sessions, remove their Storage objects, and keep foreign keys from blocking a delete.
  - [Impersonation](https://bettersupabase.com/docs/auth/impersonation.md): Let support staff view the app as a user, read-only by default, with every session recorded and audited.
  - [createServer](https://bettersupabase.com/docs/auth/server.md): Repositories bound to the caller, plus explicit admin and acting-as identities.
  - [Middleware and proxy](https://bettersupabase.com/docs/auth/middleware.md): withBetterSupabase as an @supabase/middleware entry, framework bridges, and composing the Next.js proxy with i18n, rewrites and Server-Timing.
  - [Direct Postgres](https://bettersupabase.com/docs/auth/postgres.md): The same repositories over SQL, with the same results and RLS.
  - [Problem Details](https://bettersupabase.com/docs/auth/problems.md): DbError as RFC 9457 application/problem+json, with RFC 6750 challenges.
- Frameworks
  - [Overview](https://bettersupabase.com/docs/frameworks.md): One adapter per framework runs withBetterSupabase in its middleware, so every route, loader and action gets the caller's repositories.
  - [Next.js](https://bettersupabase.com/docs/frameworks/next.md): Proxy, Server Components, route handlers, server actions and cache tags.
  - [Cache Components](https://bettersupabase.com/docs/frameworks/next-cache-components.md): Instant navigations, prefetching and role-aware UI with Next.js 16.3 Cache Components.
  - [Hono](https://bettersupabase.com/docs/frameworks/hono.md): Middleware, Result-aware handlers and REST resources matching your OpenAPI document.
  - [oRPC](https://bettersupabase.com/docs/frameworks/orpc.md): A middleware that adds the caller's repositories to the oRPC context.
  - [Expo Router](https://bettersupabase.com/docs/frameworks/expo.md): Server loaders, API routes and middleware that verify the caller and run as them.
  - [Edge Functions](https://bettersupabase.com/docs/frameworks/edge.md): Fetch handlers for Supabase Edge Functions, Deno, Bun and Workers.
  - [TanStack Start](https://bettersupabase.com/docs/frameworks/tanstack-start.md): Run withBetterSupabase as TanStack Start request middleware, with the caller's repositories in every server function.
  - [SvelteKit](https://bettersupabase.com/docs/frameworks/sveltekit.md): Run withBetterSupabase as a SvelteKit handle hook, with the caller's repositories on event.locals.
  - [React Router](https://bettersupabase.com/docs/frameworks/react-router.md): Run withBetterSupabase as React Router server middleware, with the caller's repositories in loaders and actions.
  - [H3 and Nitro 3](https://bettersupabase.com/docs/frameworks/h3.md): Run withBetterSupabase as H3 2 middleware, with the caller's repositories on event.context.
  - [Elysia](https://bettersupabase.com/docs/frameworks/elysia.md): Run withBetterSupabase around an Elysia app, with the caller's repositories derived into every route.
  - [Nuxt and Nitro 2](https://bettersupabase.com/docs/frameworks/nuxt.md): Register withBetterSupabase as Nitro 2 server middleware with the Nuxt module or toH3V1, and guard server routes.
  - [Node, Express, Fastify and Koa](https://bettersupabase.com/docs/frameworks/node.md): Run withBetterSupabase on node:http, Express, Fastify or Koa, with route guards and Problem Details errors.
  - [NestJS](https://bettersupabase.com/docs/frameworks/nestjs.md): Run withBetterSupabase as NestJS middleware, read the caller with @Ctx(), and guard routes by role.
  - [Astro](https://bettersupabase.com/docs/frameworks/astro.md): Run better-supabase as Astro middleware, guard pages, write Actions that return ActionResults, and render Storage images.
  - [SolidStart](https://bettersupabase.com/docs/frameworks/solid-start.md): Run better-supabase as SolidStart middleware and read the caller in queries, actions and API routes.
  - [MCP servers](https://bettersupabase.com/docs/frameworks/mcp.md): Tools from your tables and your own code, running as the signed-in user.
  - [Other frameworks](https://bettersupabase.com/docs/frameworks/other.md): Run withBetterSupabase in any framework through a bridge, or write an adapter with handle().
- API documents
  - [API documents](https://bettersupabase.com/docs/specs.md): Describe your API once with defineApi, then render OpenAPI 3.0, 3.1, 3.2 or the 3.3 preview from the same model and serve it with an ETag.
  - [Customize the model](https://bettersupabase.com/docs/specs/customize.md): Security and error presets, operation and component names, extend, custom routes, fragments, enrich hooks, plugin descriptions and schema comments in defineApi.
  - [OpenAPI versions](https://bettersupabase.com/docs/specs/openapi.md): What OpenAPI 3.0, 3.1, 3.2 and the 3.3 preview render from the same model, and which fields fall back to x- extensions in older versions.
  - [AsyncAPI](https://bettersupabase.com/docs/specs/asyncapi.md): Render an AsyncAPI 3.0 or 3.1 document for Realtime table changes, broadcast topics, CloudEvents, outgoing webhooks and the events actions emit, from the same model as OpenAPI.
  - [Arazzo](https://bettersupabase.com/docs/specs/arazzo.md): Render Arazzo 1.0 or 1.1 workflows over your OpenAPI and AsyncAPI documents with defineWorkflow and the built-in workflows, checked against the operations the API has.
  - [Overlays](https://bettersupabase.com/docs/specs/overlay.md): Apply OpenAPI Overlay 1.0, 1.1 and 1.2 documents to a rendered spec with better-supabase/overlay, write overlays in TypeScript, and export your changes as one.
  - [Reference UIs](https://bettersupabase.com/docs/specs/reference-ui.md): Serve an interactive API reference for your OpenAPI document with Scalar, Swagger UI, Redoc, Stoplight Elements or RapiDoc, loaded from pinned jsDelivr versions with SRI or from your own assets.
  - [Resources](https://bettersupabase.com/docs/specs/resources.md): REST resources that serve and document the same routes, with hooks for business logic, custom actions, response overrides and permissions checked by your authorizer.
  - [Diagnostics](https://bettersupabase.com/docs/specs/diagnostics.md): Every code defineApi, the OpenAPI, AsyncAPI and Arazzo renderers and their checks report, with its severity, its cause and how to fix it.
- Frontend
  - [Browser client](https://bettersupabase.com/docs/frontend/client.md): Repositories in the browser that follow the session.
  - [React Native](https://bettersupabase.com/docs/frontend/react-native.md): Repositories in Expo and React Native apps, with sessions in the device keychain.
  - [React](https://bettersupabase.com/docs/frontend/react.md): Provider, typed hooks and the server session.
  - [Vue](https://bettersupabase.com/docs/frontend/vue.md): A Vue plugin, typed composables, live queries, presence and actions from better-supabase/vue.
  - [Solid](https://bettersupabase.com/docs/frontend/solid.md): A provider and typed primitives for Solid and SolidStart from better-supabase/solid.
  - [Svelte](https://bettersupabase.com/docs/frontend/svelte.md): Svelte 5 bindings for live queries, presence, actions and the session from better-supabase/svelte.
  - [TanStack Query](https://bettersupabase.com/docs/frontend/query.md): Typed query and mutation options for every table.
  - [TanStack DB](https://bettersupabase.com/docs/frontend/tanstack-db.md): TanStack DB collections that load through a query or through @supabase-labs/tanstack-db, and write through the repositories.
  - [Live queries](https://bettersupabase.com/docs/frontend/live-queries.md): Keep any query fresh over Realtime, without sending row data over the socket.
- Platform
  - [List queries](https://bettersupabase.com/docs/platform/list.md): Search, facets, sorting and pagination from one definition, safe from the URL to SQL.
  - [Storage](https://bettersupabase.com/docs/platform/storage.md): Typed bucket paths, generated policies, and the upload flows apps keep rewriting.
  - [Realtime](https://bettersupabase.com/docs/platform/realtime.md): Typed broadcast topics with generated authorization, row-change triggers and disposable subscriptions.
  - [Edge Functions](https://bettersupabase.com/docs/platform/edge-functions.md): Typed Edge Function calls, with Standard Schema input and output and a Result on the client.
  - [Supabase Lite](https://bettersupabase.com/docs/platform/lite.md): Run better-supabase on Supabase Lite, generate types from a Lite project and test against it in memory.
- Blocks
  - [Overview](https://bettersupabase.com/docs/blocks.md): Feature modules for SaaS apps, each a set of SQL modules in your schema with an optional TypeScript side under better-supabase/blocks.
  - [createBlocks](https://bettersupabase.com/docs/blocks/create-blocks.md): Build several blocks from one set of options, and wire the siblings they share, from better-supabase/blocks.
  - [SQL modules](https://bettersupabase.com/docs/blocks/sql.md): Idempotent SQL modules for the database work every app repeats, written into your declarative schema.
  - [Access contract](https://bettersupabase.com/docs/blocks/access.md): One permission check for RLS policies and SQL modules, over a role list, your own role tables, an authorization provider or functions you already have.
  - [Organizations and invitations](https://bettersupabase.com/docs/blocks/organizations.md): Create organizations, manage members and roles, invite by email and switch the active organization, on tables you already have or tables the block creates.
  - [Profiles](https://bettersupabase.com/docs/blocks/profiles.md): A profile row per user, created on sign-up from auth metadata, with a unique username, an email mirror and columns users can't change.
  - [Audit log](https://bettersupabase.com/docs/blocks/audit.md): Record events, and list, reveal and export a tenant's audit entries as NDJSON, CSV or OCSF, and purge them per tenant's retention.
  - [Jobs, idempotency and webhook inbox](https://bettersupabase.com/docs/blocks/jobs.md): Background jobs on Supabase Queues, safe retries and exactly-once webhook handling on the Postgres you already have.
  - [Outbox](https://bettersupabase.com/docs/blocks/outbox.md): Events written in the same transaction as the change, read by named consumers with their own cursor and relayed as CloudEvents.
  - [Workflows](https://bettersupabase.com/docs/blocks/workflows.md): A run registry for any workflow engine that members read through RLS, cron schedules, counting semaphores, admission control for starts, and useWorkflowRuns over Realtime.
  - [Workflow SDK](https://bettersupabase.com/docs/blocks/workflow-sdk.md): Run the Workflow SDK on Supabase with a World over Postgres and Supabase Queues, and start runs, resume hooks and protect routes as the signed-in user.
  - [Workflow builder](https://bettersupabase.com/docs/blocks/workflow-builder.md): Graph workflows that members edit and publish per tenant, with webhook, schedule and event triggers, credentials by reference, node-level run status and alerts on failed or slow runs.
  - [Durable streams](https://bettersupabase.com/docs/blocks/streams.md): Resumable output for chats, workflows and agents, stored in Postgres or Redis, with a cancel flag the writer reads on its next write.
  - [Notifications](https://bettersupabase.com/docs/blocks/notifications.md): In-app notifications with per-recipient state, subject subscriptions, channel preferences, email and push deliveries, and realtime updates on a private topic.
  - [Push notifications](https://bettersupabase.com/docs/blocks/push.md): Push tokens per device with RLS, Expo device registration, and a sender for the Expo Push API that prunes dead tokens.
  - [Inbox](https://bettersupabase.com/docs/blocks/inbox.md): A shared inbox for support conversations from an in-app widget, Slack, WhatsApp, SMS and other channels, with assignment, internal notes, read receipts, bot handoff and realtime updates.
  - [Outgoing webhooks](https://bettersupabase.com/docs/blocks/webhooks-out.md): Signed webhooks to your customers' endpoints, with event subscriptions, retries, a queryable delivery log, secret rotation, URL checks and auto-disable.
  - [Incoming webhooks](https://bettersupabase.com/docs/blocks/webhooks-in.md): Trigger URLs a tenant hands to other systems, with hashed tokens, optional signatures, limits and an inbox.
  - [API keys](https://bettersupabase.com/docs/blocks/api-keys.md): Hashed API keys for tenants and users, with scopes, expiry, rotation, a rate limit per key and an apiKey caller in every server adapter.
  - [Settings](https://bettersupabase.com/docs/blocks/settings.md): Per-user and per-organization settings with a Standard Schema per key, defaults, typed get and set, and matching pg_jsonschema checks.
  - [Usage and quotas](https://bettersupabase.com/docs/blocks/usage.md): Count usage per tenant and meter with idempotent increments, enforce quotas per tenant or plan in RLS and RPCs, and report usage to Stripe meters.
  - [Billing](https://bettersupabase.com/docs/blocks/billing.md): Stripe customers per tenant, Checkout and the customer portal, seat sync from membership events, and Stripe webhook handling that links customers and refreshes sessions.
  - [Feature flags](https://bettersupabase.com/docs/blocks/flags.md): Feature flags per tenant and per user, with targeting rules, overrides and percentage rollouts, evaluated the same way in RLS and in an OpenFeature provider.
  - [Comments and activity](https://bettersupabase.com/docs/blocks/comments.md): Threaded comments on any record in a tenant, mentions that notify, comment events in the outbox and an activity feed built from outbox events.
  - [Attachments](https://bettersupabase.com/docs/blocks/attachments.md): Files linked to records in a tenant, uploaded through signed URLs to a private bucket and served only after a malware scan.
  - [Data lifecycle](https://bettersupabase.com/docs/blocks/data-lifecycle.md): Data exports for a user or an organization as NDJSON files in Storage, and organization deletion with a grace period, a cancel and a purge job.
  - [SSO](https://bettersupabase.com/docs/blocks/sso.md): Verified email domains with auto-join, SAML providers per organization, SSO enforcement in the access token hook, and a SCIM 2.0 endpoint that provisions memberships.
  - [Onboarding](https://bettersupabase.com/docs/blocks/onboarding.md): Onboarding checklists per user or per organization, with steps completed by hand or by an outbox event, and a useOnboarding hook.
  - [Waitlist](https://bettersupabase.com/docs/blocks/waitlist.md): A waitlist with positions and approvals, hashed invite codes with use limits and an optional organization, and a before-user-created hook that makes sign-up invite-only.
  - [Announcements](https://bettersupabase.com/docs/blocks/announcements.md): In-app announcements for everyone, some tenants, some roles or some plans within a time window, with dismissals and a useAnnouncements hook over Realtime.
  - [Entitlements](https://bettersupabase.com/docs/blocks/entitlements.md): Stripe entitlements per tenant in the access token, in RLS, and fresh again after a plan change.
  - [Vector search](https://bettersupabase.com/docs/blocks/vector-search.md): Nearest-neighbour search with pgvector that respects RLS and still returns k rows per tenant.
  - [AI chat](https://bettersupabase.com/docs/blocks/ai-chat.md): Chats, projects and a branching message tree in a canonical message format, with runs, tool approvals, share links, a model catalog per plan and moderation events.
  - [AI files](https://bettersupabase.com/docs/blocks/ai-files.md): Attachments and generated files for AI chats in a private bucket, provider file references with expiry, and versioned documents with suggested edits.
  - [Knowledge](https://bettersupabase.com/docs/blocks/knowledge.md): Documents chunked and embedded per organization, agent, project, chat or user, with hybrid search that ranks full text and vector matches together.
  - [Memory](https://bettersupabase.com/docs/blocks/memory.md): Core memory files the model edits with Anthropic's memory tool commands, archival facts found by similarity, and recall over a user's earlier messages.
  - [Agents](https://bettersupabase.com/docs/blocks/agents.md): Saved assistants with their own instructions, model, tools, connectors and knowledge, shared in an organization or a public store with installs and ratings.
  - [Connectors](https://bettersupabase.com/docs/blocks/connectors.md): MCP servers an organization connects, each user's OAuth grant behind a credential reference, MCP sessions per chat and tool list fingerprints an admin approves.
  - [AI tasks](https://bettersupabase.com/docs/blocks/ai-tasks.md): Prompts a user schedules on a cron in their time zone, a scheduler that queues each run, and a run log with the chat each run wrote to.
  - [AI cache](https://bettersupabase.com/docs/blocks/ai-cache.md): Model responses cached by a hash of the request, with a TTL, a size cap, per-tenant clearing and an hourly purge job.
  - [AI providers](https://bettersupabase.com/docs/blocks/ai-providers.md): Each tenant's own provider keys as credential references, and a registry of provider batch jobs with a poll schedule.
- Chat SDK
  - [Chat SDK](https://bettersupabase.com/docs/chat-sdk.md): Run Chat SDK bots on Supabase with a Postgres state adapter, an inbox adapter for the in-app widget, and helpers that record Slack, WhatsApp and SMS messages in the inbox.
  - [State](https://bettersupabase.com/docs/chat-sdk/state.md): createSupabaseState, a Chat SDK StateAdapter on Postgres with subscriptions, locks, a cache, lists and per-thread queues.
  - [Inbox adapter](https://bettersupabase.com/docs/chat-sdk/inbox-adapter.md): inboxAdapter, a Chat SDK adapter whose threads are inbox conversations, so a bot answers visitors in the in-app widget and staff can take over.
  - [Channels](https://bettersupabase.com/docs/chat-sdk/channels.md): Record Slack, WhatsApp, Messenger and SMS conversations in the inbox with Chat SDK adapters, deliver staff replies on their channel and keep the event store clean.
  - [React](https://bettersupabase.com/docs/chat-sdk/react.md): better-supabase/chat-sdk/react re-exports the inbox hooks for chat interfaces, a staff list, a thread with typing, and an in-app widget.
- AI SDK
  - [AI SDK](https://bettersupabase.com/docs/ai-sdk.md): Convert between AI SDK UI messages and the canonical message format, attribute spend in the AI Gateway, and keep the model catalog and costs current.
  - [Assistant](https://bettersupabase.com/docs/ai-sdk/chat.md): A chat route over the AI chat block with createAssistant, and useAssistant on the client, with resumable answers, stop, model checks, moderation and quotas.
  - [Durable chat](https://bettersupabase.com/docs/ai-sdk/workflow.md): Answers that run as Workflow SDK workflows with durableChat and durableTurn, tool approvals that wait for hours, stop through a hook, reconnects by chunk index and progress in ai_run_steps.
  - [Files](https://bettersupabase.com/docs/ai-sdk/files.md): Read supabase-storage file parts in the AI SDK's experimental_download, store generated files and cache provider file references.
  - [Embeddings](https://bettersupabase.com/docs/ai-sdk/embeddings.md): Embed knowledge with an AI SDK model or Supabase's built-in model, rerank hits, and give the model a search tool that cites its sources.
  - [Memory](https://bettersupabase.com/docs/ai-sdk/memory.md): Give the model the memory tool, Anthropic's built-in memory tool, a recall tool and its core memory, and extract facts from a conversation in a job.
  - [Agents](https://bettersupabase.com/docs/ai-sdk/agents.md): Build a ToolLoopAgent from a stored agent with its tools, approvals and knowledge search, and check input and output with a moderation middleware.
  - [MCP connectors](https://bettersupabase.com/docs/ai-sdk/mcp.md): Authorize a user with an MCP server through OAuth with dynamic client registration in Vault, connect with the stored session and give the model the server's tools.
  - [Tenant keys and sandboxes](https://bettersupabase.com/docs/ai-sdk/providers.md): Send each tenant's own provider keys to the AI Gateway as BYOK, and keep the sandbox registry current while a sandbox runs.
  - [Metering](https://bettersupabase.com/docs/ai-sdk/telemetry.md): Meter every model call on the tenant's usage meters through registerTelemetry, and reconcile each tenant's AI Gateway spend nightly.
  - [Response cache](https://bettersupabase.com/docs/ai-sdk/cache.md): A wrapLanguageModel middleware that answers repeated model calls from the AI cache block and replays cached streams.
  - [Batches](https://bettersupabase.com/docs/ai-sdk/batches.md): Start AI SDK batches for a tenant, poll them from a job, and store each request's result in Postgres.
- eve
  - [eve on Supabase](https://bettersupabase.com/docs/eve.md): Run eve agents on Supabase with the Workflow World on Postgres, Supabase sign-in on eve routes, connections over credential providers, memory, sessions in the chat tables and the inbox as a channel.
- Build
  - [Build a ChatGPT clone](https://bettersupabase.com/docs/build/chatgpt-clone.md): The modules, routes and components behind the example's /assistant and /knowledge pages, from a stored chat to tenant keys and metering.
  - [Build a workflow builder](https://bettersupabase.com/docs/build/workflow-builder.md): The modules, routes and components behind the example's /workflows pages, where members draw a graph, publish it and watch each run on the canvas.
  - [Build a unibox inbox](https://bettersupabase.com/docs/build/unibox-inbox.md): The modules, routes and components behind the example's /inbox page and Help sheet, where the assistant answers first and staff take over, plus the channel adapters that bring Slack and WhatsApp into the same list.
- Plugins
  - [Plugins](https://bettersupabase.com/docs/plugins.md): First-party plugins for the columns every app repeats.
  - [timestamps](https://bettersupabase.com/docs/plugins/timestamps.md): createdAt and updatedAt without remembering them.
  - [softDelete](https://bettersupabase.com/docs/plugins/soft-delete.md): Hide deleted rows everywhere, restore them, and avoid the RLS returning trap.
  - [tenant](https://bettersupabase.com/docs/plugins/tenant.md): Scope every query to the request's tenant, on top of RLS.
  - [actor](https://bettersupabase.com/docs/plugins/actor.md): Record who created, changed and deleted each row.
  - [validation](https://bettersupabase.com/docs/plugins/validation.md): Validate writes with zod, valibot or any Standard Schema.
  - [Query rules](https://bettersupabase.com/docs/plugins/rules.md): Runtime checks that catch unbounded reads, missing tenants, sensitive columns and admin keys in the browser.
  - [Lint rules](https://bettersupabase.com/docs/plugins/lint.md): Catch unbounded reads and unscoped deletes in the editor, with ESLint or oxlint.
- [Testing](https://bettersupabase.com/docs/testing.md): Test RLS, APIs and SQL against the local stack as real users.
- [Examples](https://bettersupabase.com/docs/examples.md): Runnable apps for every integration, built against a local stack.
- Production notes
  - [Monorepos](https://bettersupabase.com/docs/guides/monorepo.md): One runtime package owns defineSupabase and the request context; domain packages type their repositories from its db and never import the generated client.
  - [Supabase library MCP blocks](https://bettersupabase.com/docs/guides/supabase-blocks.md): Add typed repositories to the MCP server and headless app blocks from the Supabase library, or replace their tools with createMcp.
  - [Data API grants](https://bettersupabase.com/docs/guides/data-api-grants.md): Grant new tables to the Data API roles now that Supabase no longer does it for you.
  - [Read replicas](https://bettersupabase.com/docs/guides/read-replicas.md): Send reads to a Supabase read replica and keep read-your-writes after a mutation.
  - [Offline-first](https://bettersupabase.com/docs/guides/offline-first.md): Read and write on the device with PowerSync, and upload the changes through the repositories.
  - [Jobs, webhooks and agents without a session](https://bettersupabase.com/docs/guides/without-a-session.md): Run background jobs, webhook handlers and MCP tools as a specific user, so RLS keeps deciding, and keep the service role for the work no user owns.
  - [CSV downloads](https://bettersupabase.com/docs/guides/csv-downloads.md): Turn rows into RFC 4180 CSV or a download response with toCsv, csvColumns and csvResponse from better-supabase/server.
  - [Limitations](https://bettersupabase.com/docs/guides/limitations.md): What PostgREST can't do, and what better-supabase does instead.
- Migrating
  - [Overview](https://bettersupabase.com/docs/migration.md): Guides for upgrading between better-supabase versions and for moving an existing app or library onto better-supabase.
  - [Existing apps](https://bettersupabase.com/docs/migration/existing-apps.md): Bring better-supabase into an app that already has its own tables, permissions, events and middleware, one module at a time.
  - [From 0.5 to 0.6](https://bettersupabase.com/docs/migration/0.5-to-0.6.md): What to change when upgrading to better-supabase 0.6, which renames kits to blocks, moves the feature modules under better-supabase/blocks, spells out organization and replaces the PermDock settings with authorization providers.
  - [From 0.4 to 0.5](https://bettersupabase.com/docs/migration/0.4-to-0.5.md): What to change when upgrading to better-supabase 0.5, which renames SQL kit objects to the repo standard and makes the kit fail closed.
  - [From 0.3 to 0.4](https://bettersupabase.com/docs/migration/0.3-to-0.4.md): What to change when upgrading to better-supabase 0.4, which makes requests, generated types and the CLI cheaper.
  - [From 0.1 to 0.2](https://bettersupabase.com/docs/migration/0.1-to-0.2.md): What to change when upgrading to better-supabase 0.2, which renames claims and SQL functions to one claim contract.
  - [From plain supabase-js](https://bettersupabase.com/docs/migration/supabase-js.md): Move an app that calls supabase.from() directly to typed repositories, one query at a time.
  - [From supabase-cache-helpers](https://bettersupabase.com/docs/migration/supabase-cache-helpers.md): Map @supabase-cache-helpers/postgrest-react-query hooks to better-supabase.

## Reference

- CLI
  - [CLI](https://bettersupabase.com/docs/cli.md): Codegen, SQL and diagnostics for better-supabase projects.
  - [init and add](https://bettersupabase.com/docs/cli/init.md): Scaffold the config, the data layer and framework glue for your project.
  - [gen](https://bettersupabase.com/docs/cli/gen.md): Generate database types, typed models, relation metadata and validators.
  - [introspect](https://bettersupabase.com/docs/cli/introspect.md): Save a schema snapshot so codegen and doctor run without a database.
  - [Local development](https://bettersupabase.com/docs/cli/local.md): Env files, signing keys, typed seeds and OpenAPI files for the local stack.
  - [spec](https://bettersupabase.com/docs/cli/spec.md): Write, check and validate the OpenAPI, AsyncAPI and Arazzo documents your defineApi module renders, with a content-hash cache, watch mode and a diagnostics manifest.
  - [scaffold](https://bettersupabase.com/docs/cli/scaffold.md): Write an API module, a REST resource per table and an OpenAPI route for Hono or Next.js, from the tables gen found.
  - [doctor](https://bettersupabase.com/docs/cli/doctor.md): Security, performance and drift checks for your database, config.toml and env files.
  - [Configuration](https://bettersupabase.com/docs/cli/config.md): better-supabase.config.ts options and defaults.
  - [codemod](https://bettersupabase.com/docs/cli/codemod.md): Rewrite imports and calls for renamed better-supabase APIs after an upgrade.
  - [Errors](https://bettersupabase.com/docs/cli/errors.md): What each CLI error code means, its exit code, and how to fix it.
- Standards
  - [Standards registry](https://bettersupabase.com/docs/standards.md): Every standard better-supabase follows, where it is used and how mature it is.
  - [OpenAPI](https://bettersupabase.com/docs/standards/openapi.md): OpenAPI 3.0, 3.1 and 3.2 documents, and a 3.3 preview, rendered from one API model built from the generated schema.
  - [Overlay](https://bettersupabase.com/docs/standards/overlay.md): Keep changes to a generated OpenAPI or AsyncAPI document in Overlay 1.0, 1.1 or 1.2 files and apply them on every render.
  - [Arazzo](https://bettersupabase.com/docs/standards/arazzo.md): Arazzo 1.0 and 1.1 workflows over your OpenAPI and AsyncAPI documents, checked against the operations the API has.
  - [AsyncAPI](https://bettersupabase.com/docs/standards/asyncapi.md): An AsyncAPI 3.0 or 3.1 document for Realtime table changes, broadcast topics, CloudEvents and webhooks, rendered from the same API model as OpenAPI.
  - [AuthZEN](https://bettersupabase.com/docs/standards/authzen.md): How the Authorizer interface follows the AuthZEN Authorization API 1.0 information model, and what the conformance test checks.
  - [OpenTelemetry](https://bettersupabase.com/docs/standards/otel.md): Database spans, metrics and trace propagation with the OpenTelemetry conventions.
  - [CloudEvents](https://bettersupabase.com/docs/standards/events.md): Mutations as CloudEvents 1.0, for queues, buses and webhooks.
  - [Webhooks](https://bettersupabase.com/docs/standards/webhooks.md): Standard Webhooks verification, typed Supabase Auth hooks and database webhook payloads.
- [Supabase packages](https://bettersupabase.com/docs/supabase-packages.md): Which Supabase packages better-supabase builds on, how each one is installed and which docs page covers it.
- Extending
  - [Writing plugins](https://bettersupabase.com/docs/extending/plugins.md): Plugin API v1, its hooks, and typed repository extensions.
  - [Custom repositories](https://bettersupabase.com/docs/extending/repositories.md): Domain methods with defineRepository and extend, and the escape hatches below them.
  - [Extending blocks](https://bettersupabase.com/docs/extending/blocks.md): Add your own columns to a block's table, steer its methods with hooks, wrap its transport and add methods, without forking the block.
  - [Extension interfaces](https://bettersupabase.com/docs/extending/interfaces.md): The interfaces better-supabase is built on, their first-party implementations and how to plug in your own.
  - [Authorizers](https://bettersupabase.com/docs/extending/authorizers.md): The runtime authorization decision point that resources, actions, route guards and MCP tools ask for their permission, in the AuthZEN request model, failing closed.
  - [Authorization providers](https://bettersupabase.com/docs/extending/authorization-providers.md): Let another authorization system answer permission checks in the SQL modules, bucket and topic policies, API keys and doctor, through one versioned config key.
  - [Document formats](https://bettersupabase.com/docs/extending/document-formats.md): Render the API model to a standard better-supabase does not ship, such as a Postman collection or a GraphQL schema, with defineDocumentFormat and testDocumentFormat.
  - [Credentials](https://bettersupabase.com/docs/extending/credentials.md): Third-party tokens behind a credential reference, resolved by a CredentialProvider over Supabase Vault or Vercel Connect.
  - [Add a credential provider](https://bettersupabase.com/docs/extending/credential-providers.md): Write a CredentialProvider for Nango, Composio or a cloud secret manager, route refs to more than one provider, and check it with the conformance kit.
  - [Add another SDK](https://bettersupabase.com/docs/extending/add-an-sdk.md): The converter, stream and engine contracts an adapter for TanStack AI, LangChain, the OpenAI SDK or Temporal implements to use the AI and workflow blocks.
  - [Events](https://bettersupabase.com/docs/extending/events.md): Observe queries, mutations, errors, auth and refreshes with betterSupabase.on.
  - [Conformance blocks](https://bettersupabase.com/docs/extending/conformance.md): Prove a custom executor, cache adapter, sink, auth resolver, framework adapter, generator or plugin meets its contract.
  - [Stability](https://bettersupabase.com/docs/extending/stability.md): What counts as public API, how it is kept stable and how deprecations work.
- [For AI agents](https://bettersupabase.com/docs/for-ai-agents.md): Agent Skills, llms.txt, Markdown pages and a docs MCP server that help coding agents use better-supabase correctly.
- [Roadmap](https://bettersupabase.com/docs/roadmap.md): What better-supabase is building now, next and later, with the upstream source each item follows and the subpath it lands in.

## Optional

- [Full documentation](https://bettersupabase.com/llms-full.txt): every page in one Markdown file
- [Docs MCP server](https://bettersupabase.com/mcp): Streamable HTTP, read-only tools search_docs, get_page and list_pages