From 0.14 to 0.15

0.15 groups the config file, renames the runtime instance to bsb, moves the SQL engine's names from module to block and gives the CLI one command per job. better-supabase codemod 0.15 makes the changes below in your config, source files, package.json scripts and GitHub workflows. Run it, review the diff, then run better-supabase upgrade and generate a migration.

npx better-supabase codemod 0.15

The config is groupedCopy Anchor Link

better-supabase.config.ts groups its keys into database, auth, gen, api and tooling. preset, blocks, plugins, records, tables and adapters stay at the top level. A config that still uses a 0.14 key fails to load, and the message names the key's new place.

export default defineConfig({
  database: { schemas: ["public"], sql: { owner: "tenant", api: "api" } },
  auth: { organization: { claim: "tenant_id" } },
  gen: { casing: "camel", output: "src/lib/supabase/generated.ts" },
  tooling: { doctor: { strict: true } },
  records: { customer: { table: "customers", title: "name" } },
  tables: { notes: { owner: "user", columns: { body: { type: "text" } } } },
  adapters: ["next"],
  blocks: { tenant: { names: { organization: "workspace" } } },
});

Some keys take new names on the way:

Environment blocks ($env, $ci and the others) take the same groups. A better-supabase.config.json is regrouped the same way. Create designs keep appTables and scope in this release.

resolveConfig returns the same resolved config as in 0.14, so code that reads config.claims.tenant or config.appTables from a resolved config keeps working. flattenConfig and groupConfig from better-supabase/config turn one shape into the other.

The runtime instance is bsbCopy Anchor Link

The instance createBetterSupabase returns is called bsb in the docs, the templates and the request contexts: ctx.bsb, c.var.bsb, locals.bsb and context.bsb. The codemod renames bs where a file creates, imports or destructures it. Database objects better-supabase installs use the bsb_ prefix; upgrade renames the old bs_ ones.

The SQL engine says blockCopy Anchor Link

SqlModule is BlockSql, ModuleDefinition is BlockSqlDefinition, and the other Module* types from better-supabase/sql are BlockSql*. SubjectRef is RecordRef, entityForm is recordForm, ShipmentCarrier is ShippingProvider and QueueBackend is QueueProvider. Installed versions live in better_supabase.blocks; upgrade copies the rows of better_supabase.modules before the schema diff drops it.

The CLI has one command per jobCopy Anchor Link

The CLI keeps one command for each job: init, add, remove, upgrade, gen, doctor, db, dev, blocks, spec, mcp and the helpers. The commands below moved. Running an old one exits 2 and names the new one, and the codemod rewrites them in package.json scripts and GitHub workflows.

gen --out <file> now names the file gen --save-snapshot writes; the generated code still goes to --out-dir. add --force overwrites files that exist, so a block whose hooks overlap the authorization provider's needs --allow-hook-overlap. remove is new: it takes blocks out of the config and lib/blocks.ts and deletes their module files, and db diff writes the migration that drops their tables. See the CLI reference for every command.

Designs replace preset codesCopy Anchor Link

Create URLs and the CLI carry the design JSON instead of a preset code. The config's preset key takes a preset name or an object with the conventions that differ from the defaults and the blocks:

// 0.14
preset: "1pWEF3d578B1iGt16",

// 0.15
preset: { casing: "camel", scope: "user", blocks: ["profiles", "tags"] },

A Create URL is /create?preset=<name> for an unchanged named preset and /create?design=<code> otherwise, with the preset inside the design. A design file is the design JSON with its version and preset keys, without the 0.14 design wrapper. init --preset, add --preset and blocks list --preset take a name, a URL, a design code or a file, and stop on a 0.14 code with a message that names the codemod. The codemod turns a code in the config's preset into the name or object it holds, and rewrites *.design.json files.

encodePreset, decodePreset, isPresetCode, defaultPresetCode, withPresetField, PRESET_BLOCKS, PRESET_FIELDS, PRESET_VERSION and the DecodedPreset type are gone from better-supabase/preset. Use presetSpec, presetFromSpec and presetOfSpec for the config value, createUrl for a link and presetAndDesignOf to read one. designConfigSource, designInstallCommand and designApplyCommand merge into presetConfigSource, presetInstallCommand and presetApplyCommand, which take an optional design and are now async.

Blocks take plain namesCopy Anchor Link

26 blocks have new names. Each one changes in the config, the CLI, its subpath, its exports, its operation names and its CloudEvent source:

// 0.14
blocks: { tenant: {}, "work-items": {}, rules: {} },

// 0.15
blocks: { memberships: {}, tasks: {}, automations: {} },

The codemod renames the blocks keys and lists, the preset.blocks list, the operation names in auth.authorization.operations, the imports from better-supabase/blocks/<name> and the exports named after a block. It lists the event sources better-supabase/<name> it finds, so you can update your subscribers. A 0.14 name in the config stops add and gen with a message that names the codemod.

Table names, permission keys, event types, hint codes and queue names keep their 0.14 values. Run better-supabase upgrade, then db diff: the migration moves the installed blocks to their new names, and renames two tables whose names clashed with a renamed block. Hiring's jobs table becomes job_openings, and catalog's collections table becomes product_collections.

More blocks register record typesCopy Anchor Link

The quotes, invoices, orders, bookings and forms blocks register their primary noun as a record type, so records.quote, records.invoice, records.order, records.booking and records.form now fail with config_invalid. Remove the entry when it points at the block's own table. When it points at a table of your own, keep it and turn the block's record type off:

blocks: {
  bookings: { names: { booking: { subject: false } } },
},

Then run better-supabase upgrade. Every block that owns tables now declares its nouns, so blocks.<name>.names renames them; see SQL blocks.

Plugins become block extensionsCopy Anchor Link

The built-in plugins live with the blocks that own their columns, and the plugins config key goes. The codemod moves the config and the imports:

gen now installs the extensions of the installed blocks in the generated schema, and validation() with the generated validators when a zod(), valibot() or standardSchema() generator is configured. Remove the .use() calls the codemod moved unless they pass options; a .use() of an extension with options replaces the one the schema installed.

One default changed: a query on an organization table without an organization is left to RLS (onMissing: "skip"). The codemod keeps the 0.14 behavior by writing auth.organization.onMissing: "error" for a config that had plugins.tenant; set it yourself to fail closed.

One data contract for tables and blocksCopy Anchor Link

Repositories and block clients share the data verbs: list, page, get, count and aggregate read, create, update, upsert and delete write, and attach and detach link a row to a record. The codemod rewrites the repository calls:

get takes the primary key, an object with one complete unique key, or { where }. With { where } it fails with multiple_rows when more than one row matches, so it replaces findOnly. Read sets and query specs have no .map, so where the codemod wrote findFirst as a list with .map((rows) => rows[0] ?? null), use get({ where }, { optional: true }) or destructure the first row; the codemod lists those calls.

The lint rule no-empty-where reports an update or delete whose filter is { where: {} }, and no-unbounded-list reports a list without limit.

Block clients move to the same verbs. These calls are listed for review, because the names are too common to rewrite safely:

The rule builder and saved-view controllers keep save, the settings client keeps setUser and setOrganization, and domain verbs such as approve, send and publish stay.