Typed blocks

You name a block's entities once, in blocks.<name>.entities, and the SQL, the clients, the events, the permissions and the generated types all use that name. The config keys are typed from the installed blocks, so a wrong entity, column or function name fails in your editor instead of in better-supabase gen.

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

export default defineConfig({
  blocks: {
    tenant: { entities: { organization: "workspace" } },
    "work-items": {
      entities: { work_item: { name: "task", url: "/tasks/{id}" } },
    },
  },
});

With this config the SQL writes a tasks table with a workspace_id column, create_task and task.created, and gen writes tasksBlock, Task and TasksEvents into blocks.generated.ts. The tenant rename stays in SQL: event payloads and client types keep organizationId, so code that reads them works under any tenant name.

Typed config keysCopy Anchor Link

defineConfig returns the config with its literal types, and the blocks key is typed from each block's names:

The package ships the same keys as JSON Schema, in better-supabase/schemas/config-v1.json, for editors that read it.

SubjectsCopy Anchor Link

A block's entities register as subjects on their own: deals registers deal, catalog registers product and product_variant, work-items registers work_item under its final name. Comments, attachments, reactions and the other subject blocks then accept them with no entry in subjects. url sets the page subject_url returns, and subject: false keeps an entity out of the registry:

blocks: {
  catalog: { entities: { product: { url: "/admin/products/{id}" } } },
  deals: { entities: { deal: { subject: false } } },
},

A subjects entry with the name of a block entity is an error, because the block already registers it.

Renamed clientsCopy Anchor Link

For each block whose entities the config renames, gen writes the block under its new names with renameBlock. List that one in defineBlocks:

import { defineBlocks, rpcTransport } from "better-supabase/blocks";

import { blockConfig, tasksBlock } from "./supabase/blocks.generated";

export const blockSet = defineBlocks(blockConfig, { tasks: tasksBlock });

const { tasks } = blockSet.create({ transport: rpcTransport(supabase) });
const task = (await tasks.create(workspaceId, { title: "Ship it" })).orThrow();
await tasks.update([{ taskId: task.id, field: "title", value: "Shipped" }]);

Method names that contain the noun (saveWorkItem to saveTask), argument and result keys (workItemId to taskId) and event types follow the rename, and hooks keyed under tasks see the renamed client. See Renamed blocks for the transport side.

Name constantsCopy Anchor Link

blocks.generated.ts also exports the names the SQL uses, so code that checks a permission, filters events or builds a link uses a constant instead of a string:

"use server";

import * as v from "valibot";

import { bs } from "@/lib/bs";
import { blocks } from "@/lib/blocks";
import { permissions } from "@/lib/supabase/blocks.generated";

export const renameTask = bs.blockAction(
  ({ supabase }) => blocks(supabase).tasks,
  "update",
  {
    input: v.object({ taskId: v.string(), title: v.string() }),
    permission: permissions["work-items"].write,
    args: ({ taskId, title }) => [[{ taskId, field: "title", value: title }]],
  },
);

urls.task({ id: task.id }) builds the link to the same row.

Input schemasCopy Anchor Link

The entity blocks (catalog, deals, employees, parties and work-items) export a Standard Schema for each input, such as workItemInputSchema. It validates without a validation library and converts to JSON Schema. A renamed block carries its schemas under the new names, with renamed property names and titles: tasksBlock.schemas.task.input.

The zod and valibot generators write the same inputs in your validation library, named after the final noun: taskInput, taskChange and taskListFilter.

Helpers built on these typesCopy Anchor Link