Upgrading

Every @orthacms/* package is released together, at one version, and a generated app pins each exactly (no caret). An upgrade = one version bump across the set + orthacms migrate.

The lockstep rule

Several packages must share one copy of a dependency — React contexts, the design system’s tokens, the plugin contract. Two versions of @orthacms/design-system means two React contexts and an admin that silently stops working.

Bumping

Install every @orthacms/* package you have at the new version, in one npm install:

NEW=0.13.1
npm install $(node -e '
    const m = require("./package.json");
    const names = Object.keys({ ...m.dependencies, ...m.devDependencies })
        .filter((n) => n.startsWith("@orthacms/"));
    console.log(names.map((n) => n + "@" + process.argv[1]).join(" "));
' "$NEW")

npm ls @orthacms/design-system react   # exactly one entry each

Adding a package you did not have (GraphQL, a storage provider, a copilot backend)? Install it at the set’s version — never @latest alone.

Migrate, forward

npx orthacms migrate

• Builds the server, then applies every plugin’s pending migrations in plugin order.
• Run it once, as a release step, before the new version starts — not at boot.
• Forward-only. No down. Rolling back = the previous app version on a migrated database: fine for additive migrations, not destructive ones. Read the SQL and take a backup first.

Release order:

1. Bump the set, npm install
2. orthacms build
3. orthacms migrate
4. Start the new version
5. Stop the old one

What each release changed

Read down from your current version. Only changes that need action are listed; the changelog has the rest.

0.13.1

A patch release, with nothing to migrate and nothing to change. The far side of a single relation — author.articles mirroring article.author, say — is now listed read-only in the record editor, with no Add and no Remove, under “Linked from Articles — change it there.” It used to offer both, and the save then failed with Relation "author.articles" owns no writable links from this side, because each of those links is an article’s own foreign key. The admin learns this from the schema: GET /api/content-schema now gives every inverse relation inverse.writable, false for the inverse of a single relation. The write API is unchanged — a delta on that field is still a 400.

0.13.0

Three migrations, all additive. Nothing in your code has to change; a host that overrides mail copy, or an admin plugin of your own, may want a look at the rows below.

New routes, all additive: DELETE /api/users/:id/sessions (sign out everywhere), POST /api/users/invites/batch, GET /api/users/roles, GET /api/users/:id/sign-in, GET /api/workspaces/:id/archive-impact, GET /api/protection/queue/approved, GET /api/activity/export (CSV), GET /api/segments/:id/usage, GET /api/copilot/suggestions, and the Insights drill-downs …/content/stale/records, …/content/unshipped/records and …/media/alt/missing. Existing responses gain fields: GET /api/users takes ?role= and returns counts and each member’s lastActiveAt; GET /api/api-tokens takes ?status= and ?q= and returns createdBy and a summary; GET /api/activity takes ?q=; PATCH /api/alarms/rules/:id returns the rescan as scan, and switching a rule back on rescans; findings carry entryTitle; the review queue’s lines carry fieldsChanged. See endpoints.

Also new, with nothing to do: members get quick filters, Last active and an Invite people page that invites several people at once; workspaces are cards that say what is inside, a three-step create ends on a ready page, and Archive… says what it touches first; the Content Model page is fields first, with a kind picker, a field panel with a preview, type templates and a one-page review; Reviews has Waiting on me, My requests and Recently approved tabs and a review panel with Approve; the Activity log has a search box, a time range, an event panel, Export CSV and Retry all; audiences show where they are used and can be tried against a reader’s tags; alarms name flagged records by title, switch on and off, and preview Right now while you edit; Ortha CMS AI opens with suggestions written for the workspace, shows a write’s change on the permission prompt (now Allow once, Allow for this chat, Don’t allow), edits skills in a sheet, and keeps collapsed chats as pills; and the API Tokens page names each token’s creator, flags expiries and offers a ready curl request when a token is created.

0.12.0

An admin-only release: no migration, no API change, no new setting. Nothing an app or an API client does has to change; an admin plugin of your own may want a look at the rows below.

Also new, with nothing to do: the record’s title is the editor’s heading, with its status, language and save state on one line under it; the header’s actions read Save draft, Publish or Publish changes, and say Published · up to date when there is nothing to do; ⌘S, ⌘⇧P and ⌘. save, publish and open Properties (⌘S takes over the browser’s own Save page while the editor is open). Properties no longer docks by default: it is a panel over the page, and an editor who wants the column back pins it, once per browser. The ⋯ menu loses Save draft and Save & publish, which are the buttons now. On the records page Trash is a tab at the end of the views, and Export sits in the selection bar. The Content Library opens on an overview of the workspace, the records page shows saved views as tabs with status chips, the Media Library has type chips, a list view and a details panel beside the grid, and Home, webhooks, workspaces, alarms, reviews and workspace settings are redrawn. See the entry editor.

0.11.0

Two migrations, both additive. Nothing in your code has to change.

Also new, with nothing to do: a save, a version restore and a publish-a-version in the admin that would change other languages or other records now always ask first, with a preview of every row they change; the sidebar, the right panel, the Agents rail and the media library’s folders column resize by dragging their edge; pages cross-fade, dialogs and tooltips ease in, and tab indicators slide (none of it under reduced motion); and the Ask Ortha AI launcher and the Agents switch drop their count, showing only a dot while a chat waits for your answer. A translation created after other records linked its group now fills their mirrored links in its language, instead of waiting for their next save, and a link added or removed from the inverse side of a synced many-relation now reaches the owner’s other languages, as a save of the owner would.

For API clients: askBeforeSiblingSync is read on a create and on the two version routes as well as an update, and its 422 now carries changes — each other row and what changes in it — beside locales and siblings; its message is reworded, so branch on code. See errors.

createAdmin takes a new preloadPages option (default true): once the admin is idle it fetches every page’s code in the background, so a first visit does not flash a skeleton. A newly generated app’s apps/admin/src/main.tsx passes preloadPages: !import.meta.env.DEV, so the dev server does not transform the whole admin on every reload — add that line to an existing app if its dev server feels slower after the upgrade.

0.10.3

A patch release, with nothing to migrate and nothing to change. A save in the admin that reaches other languages — a shared field, or a relation synced across locales — now asks once, naming every language it changes and any published one it would leave incomplete; it used to ask twice. A record with no other translations no longer asks at all. The admin gets that answer from the server with a new opt-in flag on PATCH /api/content/:type/:id, askBeforeSiblingSync, which refuses the save with a 422 code: "content.sibling_sync_unconfirmed" and writes nothing. A client that never sends the flag sees no difference.

0.10.2

A patch release, with nothing to migrate and nothing to change. One response gains detail: a save refused because it would leave a published translation failing validation is still a 422, now with code: "content.sibling_invalidated" and every affected locale in siblings: [{ locale, issues }] — so a client can tell those issues are not about the row it sent. In the admin the same save asks first and offers Save anyway. Delete confirmations now say what links to the entry, a link to a record in the trash shows that record’s title with an In trash mark, and trashing one translation of a record no longer unlinks it from the other languages on their next save.

0.10.1

A patch release, with nothing to migrate and nothing to change — every change is in the admin. A row in the Agents rail now marks a thread that is working (a spinner) or waiting for your answer (an amber dot). Switching an entry’s language happens at once: the cover that used to hold the page for the better part of a second is gone, and opening the locale menu prefetches the saved translations. In the schema builder, a select’s options move from Validation to General, above the default that is picked from them; groups are dragged into order by their own handle and edited from their own menu; and a list makes room for a field while it is still being dragged.

0.10.0

One migration, and one change for anyone who wrote their own storage provider.

Also new: a field can carry a default value that prefills the create form, the locale menu is searchable and lists the default locale first, the sidebar’s Agents switch shows the status of open chats, and the admin and the scaffolded app have a favicon. The copilot’s message limit rises to 32,000 characters and the composer enforces it.

0.9.1

A patch release, with nothing to migrate and nothing to change. The entry editor gains an outline of the General tab’s fields at its edge, and the copilot starts a new chat on the last model you picked. Three fixes change what a reader or an agent sees: the records list’s “Can be seen by” filter now matches who can actually read the entry, an agent reads only the type schema of the workspace it is working in, and the alarm editor offers only the workspace’s own collections.

0.9.0

A redesign of the admin, and nothing to migrate. The work area floats as one white card on the sidebar’s frame, page titles fold into the top bar along with the page’s actions and tabs, list tables run full width without a frame, and “Ask Ortha AI” moves under the work area. An app generated from 0.8.0 already has the light sidebar tokens, so its stylesheet needs no change.

0.8.0

The schema builder. It adds no migrations and owns no tables, so orthacms migrate has nothing new to run. The one new permission, schema:manage, reaches administrators when the new version boots, because the seeder reconciles the grants. An app generated before 0.8.0 runs unchanged. It just doesn’t get the Content Model page until you wire it.

Wire the builder into an app generated before 0.8.0:

1. Install both halves at the set’s version, plus drizzle-kit:

   npm install @orthacms/schema-builder-server@0.8.0 @orthacms/schema-builder-admin@0.8.0
   npm install -D drizzle-kit

2. Move your types to the conventional paths. Each file sits at src/content/collections/<name>.ts or src/content/pages/<name>.ts and exports a type named <name>. Then generate the manifest:

   npx orthacms content sync      # writes apps/server/src/content/index.ts

3. Register ContentPlugin({ types: contentTypes, migrations }) from the manifest, SchemaBuilderPlugin(config.plugins.schemaBuilder) after content on the server, and SchemaBuilderPlugin() in the admin. Add config/schema-builder.ts and drizzle.config.ts. Snippets are on the plugin page and in migrations.

4. Switch the server tsconfig to "module": "node16" and "moduleResolution": "node16", and exclude drizzle.config.ts. The old node resolution cannot resolve @orthacms/content-server/define.

5. Ignore the scratch folder. Add .orthacms to .gitignore.

6. Hand types over if you want the builder to edit them: put // @orthacms-generated on a type file’s first line. Any type without the marker stays read-only on the page.

Leave SCHEMA_BUILDER unset in production. The page is read-only there whatever the flag says.

0.7.0

Shared workspaces, form layout, and reader tags by header. Three migrations: workspaces gains is_shared and per-source shared content grants, protection gains a review-request resolution column — so orthacms migrate is not optional. Nothing is shared, and no form changes, until you opt in.

Wire the reader-tag header in an app generated before 0.7.0:

// apps/server/config/segments.ts
import { headerSegmentResolver, type SegmentsPluginConfig } from '@orthacms/segments-server';
import { readEnv } from '@orthacms/utils-server';

export function segmentsConfig(): SegmentsPluginConfig {
    return {
        resolver: headerSegmentResolver(
            readEnv('SEGMENTS_READER_TAGS_HEADER') ?? 'x-reader-tags'
        )
    };
}

curl https://cms.example.com/api/v1/content/article \
  -H 'Authorization: Bearer orthacms_…' \
  -H 'X-Reader-Tags: premium, eu'

Share a library workspace and grant one of its types to a consumer (a session with workspaces:update that is a member of the workspace being changed):

# 1. flag the source as shared
curl -X PATCH -b jar.txt -H 'Content-Type: application/json' \
  -d '{"isShared": true}' \
  https://cms.example.com/api/workspaces/<library-id>

# 2. let the consumer read the library's "tag" records
curl -X POST -b jar.txt -H 'Content-Type: application/json' \
  -d '{"slug": "tag", "sourceWorkspaceId": "<library-id>"}' \
  https://cms.example.com/api/workspaces/<consumer-id>/content

# revoke that shared grant (the consumer's own "tag" grant is untouched)
curl -X DELETE -b jar.txt \
  "https://cms.example.com/api/workspaces/<consumer-id>/content/tag?source=<library-id>"

Or in the admin: the source’s Settings → Sharing, then the consumer’s Settings → Content types. See workspaces.

Form layout in a content type:

export const event = collection('event', {
    label: 'Events',
    groups: {
        schedule: { label: 'Schedule' },
        seo: { label: 'SEO', description: 'Search and sharing.', collapsed: true }
    },
    fields: {
        title: field.text({ required: true }),
        startsAt: field.datetime({ admin: { group: 'schedule', row: 'when' } }),
        endsAt: field.datetime({ admin: { group: 'schedule', row: 'when' } }),
        venue: field.text({ admin: { group: 'schedule', width: 'half' } }),
        metaTitle: field.text({ admin: { group: 'seo' } })
    }
});

0.6.0

The ortha → orthacms rename around the packages (the @orthacms/* names are unchanged). Nothing is aliased — an old name is simply not read. Five migrations: an outbox pruning index, mail_deliveries, and protection’s tables (the last two only if you register those plugins).

The database name in DATABASE_URL is yours, and nothing reads it: only the template’s default changed. Keep the database you have.

0.5.2

A create-orthacms-app fix; nothing to do for the upgrade itself. But an app generated by 0.5.1 or earlier registers WebhooksPlugin() with no config, so every WEBHOOKS_* key in its .env is silently ignored — including the two ALLOW flags.

0.5.1

Packaging only — a release staged one package without its licence field and one build’s output was not what shipped. Nothing to do beyond the bump.

0.5.0

Migrations for webhooks (three tables), the activity log (actor type, workspace column) and the outbox (retry backoff, last error).

0.4.1 – 0.4.3

No breaking changes. 0.4.3 adds tables — alarms, reader segments, saved list views — so orthacms migrate is not optional. create-orthacms-app fixes in 0.4.1 and 0.4.2 affect only apps scaffolded afterwards.

0.4.0

0.3.0

Adding webhooks to an older app

Bumping does not add the plugin. Install @orthacms/webhooks-server and @orthacms/webhooks-admin at the set’s version, then:

// apps/server/src/plugins.ts (with a config/webhooks.ts copied from a fresh app)
WebhooksPlugin(config.plugins.webhooks),
// apps/admin/src/plugins.ts
WebhooksPlugin(),

and run npx orthacms migrate (three tables).

@orthacms/copilot-provider-fake is no longer published. A deployment that used it must configure a real backend or keep COPILOT_ENABLED=false.

What to read next

• Deployment — the release order in the context of the whole process, and the reverse proxy.
• Database and migrations — the plugin-order constraint a failed migration usually means.
• Troubleshooting — the symptom a partial upgrade produces, and the others.