Designs and the resolver

better-supabase/preset is the model behind preset in the config and behind Create. It runs on every runtime, including the browser: the resolver reads a generated catalog of the blocks and never imports the SQL renderers.

import {
  presetConfigSource,
  presetFromSpec,
  resolvePreset,
} from "better-supabase/preset";

const preset = presetFromSpec({ api: "api", blocks: ["comments"] });
const resolved = resolvePreset(preset);
// resolved.blocks: comments, plus tenant, access and updated-at, each with a reason
console.log(await presetConfigSource(resolved));

The preset keyCopy Anchor Link

The config's preset key takes a preset name, such as "saas", or an object with the conventions that differ from the defaults and the blocks to install:

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

export default defineConfig({
  preset: { casing: "camel", access: "provider", blocks: ["profiles", "tags"] },
});

presetSpec(preset) turns a Preset into that value: the name when the preset equals a named one, otherwise the object with only the fields that differ. presetFromSpec and presetOfSpec read it back; presetOfSpec takes an unknown value and throws for an unknown field or value. CONVENTION_FIELDS lists the fields in a fixed order.

ConventionsCopy Anchor Link

Every field has a default, so a preset sets only what differs.

DesignsCopy Anchor Link

A design is plain JSON: the preset, the app tables, extra columns on block tables and where each table sits on the Create canvas. It rides on a Create URL as ?design=, compressed:

import {
  createUrl,
  encodeDesign,
  namedPreset,
  presetAndDesignOf,
  presetInstallCommand,
  resolvePreset,
} from "better-supabase/preset";

const resolved = resolvePreset(namedPreset("crm"));

const design = {
  appTables: { projects: { columns: { name: { type: "text" } } } },
  extraColumns: { organizations: { tier: "text" } },
  positions: { "public.projects": [120, 40] },
};

await createUrl(resolved, design);
// https://app.bettersupabase.com/create?design=0...

await presetInstallCommand(resolved, design);
// npx better-supabase init --preset "https://app.bettersupabase.com/create?design=0..."

const { preset, design: read } = await presetAndDesignOf(
  await createUrl(resolved, design),
);

createUrl writes ?preset=<name> for a named preset with nothing else, and ?design=<code> with the preset inside the design otherwise. presetAndDesignOf reads a preset name, a Create URL or a bare design code: the design's own preset comes first, then a preset= parameter, then the default preset. The preset key takes a name or an object, as in the config.

A design code starts with 0, which no preset name starts with, followed by base64url of the design's JSON compressed with deflate-raw. It uses CompressionStream, so encoding and decoding are async and run on every runtime.

The JSON's own format goes in a version key. designFormat(design) returns the lowest format that reads the design: 1 when a table or column uses a key added after the first release (format, options, min, max, comment, identity, or a table's id, unique, indexes or comment), 2 for a table subject, 3 for rollups or lookups, 4 for events or subject versions, 5 for column access, 6 for column encrypted or table auditReads, 7 for preset, and 0 otherwise. DESIGN_FORMAT is the newest format this release reads; a code with a higher version fails with a message to update better-supabase instead of losing keys.

Codes from 0.14Copy Anchor Link

Releases up to 0.14 wrote a separate preset code (?preset=1...). Reading one now throws an error that names better-supabase codemod 0.15, which turns a code in the config's preset into the name or object it holds, and a 0.14 design file into a design with its preset inside.

decodeDesign and designOf reject what isn't a design: an unknown key, a table that tables wouldn't accept, a column type outside a plain SQL type, a block with no table for extra columns, or a code that inflates past 256 KB. encodeDesign throws a DesignParseError for an invalid design, and a DesignTooLongError (a DesignParseError with the code's length) when a valid design would pass MAX_DESIGN_CODE_LENGTH (6000 characters); write a design file then. Check for DesignTooLongError to tell the two apart.

parseDesign(value) checks the shape of a design object, such as a JSON body or an AI tool's input, with the same rules, and returns it with its empty parts dropped. It throws a DesignParseError naming the first problem. To check a design against a preset as well, use checkDesign.

safeParseDesign(value) runs the same checks without throwing, so a route handler can answer a bad body with a 400 and the issue:

import { safeParseDesign } from "better-supabase/preset";

const result = safeParseDesign(await request.json());

if (!result.ok) {
  return Response.json({ issues: result.issues }, { status: 400 });
}

// result.design is the checked design

designSchema is the same check as a Standard Schema (v1), for a library that takes one, such as a form library, a router or an AI SDK tool. Its output is the design with its empty parts dropped, and each issue's path lists the keys of the JSON Pointer below:

import { designSchema } from "better-supabase/preset";

const result = await designSchema["~standard"].validate(body);
// { value: { appTables: { ... } } } or { issues: [{ message, path: ["appTables", "tasks"] }] }

schemas/design-v1.json is the JSON Schema of a design's shape, for an editor or a tool outside TypeScript. It accepts what designSchema accepts for the shape; the names, defaults and limits are checked only by designSchema and parseDesign.

A DesignParseError is a TypeError with a code and a path, and each issue in issues is the same three keys as plain JSON. path is a JSON Pointer to the key at fault, such as /appTables/tasks/columns/title/type, or its nearest parent when the key is missing. The codes are stable; the messages may change.

Design filesCopy Anchor Link

A design too long for a URL travels as a file instead. designFileSource writes it, and init --preset and add --preset read it from a path ending in .json. DESIGN_FILE is the default name, better-supabase.design.json.

import {
  defaultPreset,
  designFileSource,
  readDesignFile,
  resolvePreset,
} from "better-supabase/preset";

const source = designFileSource(resolvePreset(defaultPreset()), design);
// {
//   "version": 7,
//   "preset": "saas",
//   "appTables": { ... },
//   "extraColumns": { ... }
// }

const { preset, design: read } = readDesignFile(source);

The file is the design JSON with its version and preset, with no length limit. readDesignFile checks it with the same rules as parseDesign, needs a preset, and throws a DesignParseError for anything else. safeDesignFileSource(resolved, design) returns { ok: true, source } or the issues instead of throwing.

Two helpers check a design before it is encoded. appReservedColumns(tenant) lists the columns every app table can get from its scope (id, created_at, updated_at, user_id and <tenant>_id), which a design's columns may not name. isAppDefault(type, value) says whether a column of type accepts value as its default.

diffDesigns(before, after) lists what changes between two designs, and diffAppTables(before, after, { keepMissing }) does the same for two appTables objects; with keepMissing: true, a table missing from after is kept instead of dropped, as add --preset merges a design. Each DesignChange has a kind, the table and column, a one-sentence summary, and breaking. A dropped or renamed table or column, a type change and a column made required without a default are breaking, and their steps give the expand-and-contract migration that makes them safe. A change to a table's rollups or lookups is the safe table.computed, because their view keeps no rows. A change to its events is the safe table.events and a change to its subject's versions is the safe table.versions, because each only replaces a trigger:

import { diffAppTables } from "better-supabase/preset";

const changes = diffAppTables(
  { notes: { columns: { body: { type: "jsonb" } } } },
  { notes: { columns: { body: { type: "text" } } } },
);
// [{ kind: "column.type", table: "notes", column: "body", breaking: true,
//    summary: "Changes notes.body from jsonb to text.", steps: [...] }]

The AI instructions for a design are at /create/prompt.md?design=<code>, or /create/prompt.md?preset=<name> for a named preset.

The default presetCopy Anchor Link

DEFAULT_PRESET_NAME is "saas", the preset /create and init start from. defaultPreset() returns it as a Preset, so an app that opens a new design doesn't hard-code it.

ResolvingCopy Anchor Link

resolvePreset(preset) returns:

What a block requires can depend on the access model: under provider and custom, access no longer requires tenant. presetBlockConflict says why one block can't install before it is selected, which is how Create disables a block.

defineConfig throws when a preset has conflicts, listing each one.

Generated filesCopy Anchor Link

presetConfigSource, presetInstallCommand and presetApplyCommand are async, because the URL in their output is.

scripts/build-catalog.ts writes the catalog (src/preset/catalog.generated.ts) from the SQL module registry and the block manifests, and pnpm catalog:check fails when it is stale.