Schema builder plugin

The plugin behind the admin’s Content Model page. It reads the running content registry and, in development, plans and applies a change as TypeScript under src/content/ plus a drizzle-kit migration. It owns no tables: its state is your source tree and a gitignored scratch folder.

How to use it is in the schema builder guide. This page is the plugin’s surface.

Install and register

create-orthacms-app installs and registers both halves in every app, with editing off, since 0.8.0. For an older app, see upgrading.

npm install @orthacms/schema-builder-server @orthacms/schema-builder-admin

// apps/server/src/plugins.ts
import { SchemaBuilderPlugin } from '@orthacms/schema-builder-server';

// after content — it reads content's registry. Read-only unless
// SCHEMA_BUILDER=true outside production; it owns no schema.
SchemaBuilderPlugin(config.plugins.schemaBuilder);

// apps/admin/src/plugins.ts
import { SchemaBuilderPlugin } from '@orthacms/schema-builder-admin';

SchemaBuilderPlugin(); // the Content Model entry in the Directory group

It owns no tables, so its position decides nothing about migrations. The composition root registers it straight after GraphQL (after saved views when GraphQL is off), with the other content consumers.

Configuration

apps/server/config/schema-builder.ts, assembled under plugins.schemaBuilder:

// apps/server/config/schema-builder.ts
import { resolve } from 'node:path';
import type { SchemaBuilderPluginConfig } from '@orthacms/schema-builder-server';
import { isProduction, readEnv, readFlag } from '@orthacms/utils-server';

export function schemaBuilderConfig(): SchemaBuilderPluginConfig {
    const restart = readEnv('SCHEMA_BUILDER_RESTART');
    return {
        enabled: readFlag('SCHEMA_BUILDER', false),
        production: isProduction(),
        projectRoot: resolve(readEnv('SCHEMA_BUILDER_ROOT') ?? 'apps/server'),
        restart: restart === 'manual' ? 'manual' : 'watch'
    };
}

The plugin config also takes, in code:

prettier and drizzle-kit are resolved from your app first, so its versions write its files. Neither run needs a database: generating only diffs snapshots.

Routes

All under /api, global — no X-Workspace-Id. Session cookie, plus RBAC.

• Editable means SCHEMA_BUILDER=true, a non-production NODE_ENV, the source tree on disk and a generated manifest. Otherwise plan and apply answer 403 schema-builder.disabled, whatever the caller’s role.
• baseFingerprint is the 16-hex fingerprint the draft started from; a different one is 409 schema-builder.stale.
• confirmed lists the id of every destructive change — at most 500.
• migrationName must match ^[a-z][a-z0-9_]{0,59}$: it ends up in a file name.
• An operation goes running (step generate, migrate, publish) → succeeded or failed. One recorded by a process that since restarted reads interrupted.
• After succeeded, poll the document route until bootId changes: a 200 from the old process is not the restart.

curl -b cookies.txt http://localhost:3000/api/schema-builder/document

{
    "document": {
        "version": 1,
        "types": [
            { "name": "recipe", "kind": "collection", "label": "Recipes", "origin": "builder", "…": "…" }
        ]
    },
    "fingerprint": "9f2c41a07be3d655",
    "bootId": "…",
    "capabilities": { "editable": false, "reason": "disabled", "restart": "watch" }
}

Errors carry { statusCode, code, message, details? }:

Permission

schema:manage came with the schema builder. No API-token scope carries it: an apply changes every workspace at once, runs DDL and writes the repository. And holding it is not enough — on a server that may not edit, it opens nothing. See permissions.

Event

One schema.applied per successful apply, through the outbox — aggregate schema, id the operation id. changes holds the applied change ids, migrations the generated migration files (none for a code-only change) and files what was written under src/content/:

{
    "operationId": "…",
    "actorId": "…",
    "changes": ["…"],
    "migrations": ["…"],
    "files": ["…"]
}

The activity log does not render it yet, and webhooks do not offer it — it is not an entry event.

What it relies on

• Content — the running ContentTypeRegistry, and the row counts behind the verdicts.
• Workspaces — grants, to block removing a type in use; the grant card on the applied page calls POST /api/workspaces/:id/content.
• Database — drizzle’s migrator for the host’s content migrations.
• The dev watcher — npm run dev or orthacms dev restarts the server on the new src/. The plugin never restarts anything itself.