Configuration

The CLI looks for better-supabase.config.{ts,mts,js,mjs,json} in the working directory, then in each parent directory up to the one that holds .git, and loads the first it finds. Paths in the file (output, sql.dir and the rest) are relative to the directory that holds it, so a config at the repository root works when the CLI runs from a package. --config overrides the search. TypeScript configs load natively on Node 24.

import { defineConfig, zod } from "better-supabase/config";
import { CustomerMetadata } from "./src/types.ts";

export default defineConfig({
  source: { projectRef: "abcdefghijklmnopqrst" },
  schemas: ["public"],
  casing: "camel",
  output: "src/lib/supabase/generated.ts",
  codecs: { int8: "bigint", numeric: "string", timestamptz: "instant" },
  json: {
    "customers.metadata": {
      import: "./src/types.ts#CustomerMetadata",
      schema: CustomerMetadata,
    },
    "notes.attachments": {
      type: "{ files: { name: string; size: number }[] }",
    },
  },
  sensitive: ["contacts.email", "contacts.phone"],
  tables: {
    customers: { relations: { primaryContact: "contact" } },
    internal_jobs: { exclude: true },
  },
  plugins: {
    timestamps: true,
    softDelete: { column: "archived_at" },
    tenant: { column: "organization_id" },
    actor: true,
  },
  realtime: { tables: ["customers", "notes"] },
  generators: [zod()],
});

OptionsCopy Anchor Link

Flags and the configCopy Anchor Link

Every option a command takes on each run has a config key, so the command line stays short and a fresh checkout behaves the same as yours. A value is picked in this order:

1. the flag, for one run;
2. the active environment block;
3. the config;
4. the default.

doctor.output applies when the report uses doctor.format, so doctor --json prints to stdout even when the config writes SARIF to a file. scaffold api and add print the config entry for the flags you passed, so you can paste it once instead of repeating them.

EnvironmentsCopy Anchor Link

An environment block overrides part of the config for one environment. Name blocks under $env, or use the $development, $production, $test and $ci shorthands:

export default defineConfig({
  casing: "camel",
  doctor: { ignore: ["BS204"] },
  $ci: {
    gen: { tasks: ["types", "sql", "spec"] },
    doctor: { format: "sarif", output: "doctor.sarif", strict: true },
  },
  $env: {
    staging: { source: { projectRef: "abcdefghijklmnopqrst" } },
  },
});

The CLI applies the block named by --env, then by $BETTER_SUPABASE_ENV, and in CI ($CI is set) the ci block. When both $env.<name> and a shorthand exist for the same name, the shorthand applies last. Objects merge key by key, while lists and other values replace the base value: above, ci keeps doctor.ignore and replaces gen.tasks. An environment without a block uses the config as it is. A block can't hold another block.

ClaimsCopy Anchor Link

The claims block names the claims every part of better-supabase reads, so a rename happens in one place. The defaults are:

export default defineConfig({
  claims: {
    tenant: "tenant_id", // the active tenant, also read from app_metadata
    scope: "tenant", // memberships[].scope written by the tenant SQL module
    features: "features", // plan features per tenant, from the entitlements module
    memberships: "memberships", // the caller's memberships, from the tenant module or a provider's hook
  },
});

gen writes the names that differ from the defaults into the generated schema, and sql add and sql sync render them into the SQL modules. Run both after changing the block.

An adapter that reads these claims itself takes the paths from claimPaths in better-supabase/config instead of hardcoding them. DEFAULT_CLAIMS holds the defaults:

import { claimPaths } from "better-supabase/config";

const paths = claimPaths(config.claims);
// { tenant: ["tenant_id", "app_metadata.tenant_id"], features: "features",
//   memberships: "memberships", scope: "tenant" }

supabase/config.tomlCopy Anchor Link

The CLI reads supabase/config.toml for the local database port, the auth settings doctor checks and bucket drift. When @supabase/config is installed, it parses the file, with env() values filled in the same way the Supabase CLI does. It's an optional peer (it needs effect and @effect/platform-node). Without it, a built-in parser reads the subset of TOML that supabase init writes.

JSON configsCopy Anchor Link

{
  "$schema": "https://unpkg.com/better-supabase/schemas/config-v1.json",
  "casing": "camel",
  "plugins": { "timestamps": true }
}

The JSON Schema gives editor completion and validation. Generators and Standard Schema values in json[...].schema need a TypeScript or JavaScript config; a JSON config can use plain JSON Schema objects.

Print the resolved configCopy Anchor Link

pnpm better-supabase config

config prints the file it loaded and the active environment, then the config with every default filled in and that environment's block merged in, as JSON (--json wraps them in one document, with environment set to the name or null). better-supabase config --env ci shows what CI will see. Generators show as their name and apiVersion, and the password in source.dbUrl is redacted. Use it to check which file the CLI found and what an option resolved to.

gen warns about tables and json keys that match nothing in the configured schemas, such as a misspelled table name, instead of ignoring them.

Custom generatorsCopy Anchor Link

import type { Generator } from "better-supabase/config";

export const tableList: Generator = {
  apiVersion: 1,
  name: "table-list",
  generate: ({ model }) => [
    {
      path: "src/lib/tables.json",
      contents: JSON.stringify(
        model.tables.map((table) => ({
          key: table.key,
          columns: table.columns.map((column) => [column.app, column.tsType]),
        })),
      ),
    },
  ],
};

A generator receives the schema metadata (meta), the typegen introspection, the resolved config, an importPath helper and model: the tables and enums gen emitted, with the TypeScript type it wrote for each column after json overrides, codecs and enum unions. model is frozen. The generator returns files, and gen --check covers them too.

apiVersion: 1 names the generator contract it targets. gen refuses a generator that declares a version it doesn't know, so a generator written for a later contract fails with a message instead of misreading its input. Leaving it out means version 1.

gen records the files it wrote in node_modules/.cache/better-supabase/gen-manifest.json. When a later run no longer writes one of them (you removed a generator or changed output), it deletes the file and lists it as removed, and gen --check reports it as no longer generated. Files that no earlier run wrote are never touched. Prove a generator with testGenerator.