Upgrading

Every @apograph/* package is released together, at one version, and a generated app pins each of them exactly with no caret. An upgrade is therefore one number changing in many places at once, followed by apograph migrate.

The lockstep rule

The packages resolve each other by name, and several of them share a dependency they must hold one copy of — React contexts in the admin, the design system’s tokens, the bootstrap host’s plugin contract. Two versions of @apograph/design-system in node_modules means two React context instances, and an admin whose sidebar silently stops talking to its provider.

Bumping

List the packages you have, and install every one of them at the new version in a single npm install:

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

One command, so npm resolves the whole set at once and does not stage a tree with half of it moved. Then confirm there is exactly one copy of the shared packages:

npm ls @apograph/design-system react

Two entries for either is a partial upgrade — fix it before booting.

Adding a package you did not have — the GraphQL adapter, a storage provider, a copilot backend — follows the same rule: install it at the version the rest are on, never @latest on its own.

Migrate, forward

npx apograph migrate

It builds the server first, then reads the compiled config and plugin list and applies every plugin’s pending migrations in plugin-list order. Run it as a release step, once, before the new version starts — not at boot, where every replica would run it in parallel.

Migrations are forward-only. There is no down. A rollback is a deploy of the previous application version against a database that has already migrated, which works for an additive migration and does not for a destructive one. Read the SQL a release adds before you plan the rollback, and take a backup before you run it.

The release order is the same every time:

1. Bump the set, npm install
2. apograph build
3. apograph 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 something from you are listed; the changelog has the rest.

0.5.2

No tables and no API change: the fix is to create-apograph-app, so upgrading an existing app needs nothing. It is worth reading anyway if your app was generated by 0.5.1 or earlier, because that app carries five settings that do nothing.

Its .env documents WEBHOOKS_DELIVERY_INTERVAL, WEBHOOKS_TIMEOUT, WEBHOOKS_RETENTION_DAYS, WEBHOOKS_ALLOW_INSECURE_URLS and WEBHOOKS_ALLOW_PRIVATE_NETWORKS — but the generated plugins.ts registered WebhooksPlugin() with no argument and no config/webhooks.ts existed to read them. Setting one changed nothing, silently: an unread environment variable is not an error. The two ALLOW flags are the ones that bite, because turning either on is how you reach a receiver on plain HTTP or inside your own network, and it appeared to have no effect.

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

Three plugins add tables, so apograph migrate is not optional: webhooks brings its own three, the activity log gains an actor type and a workspace column, and the outbox gains a retry backoff and a last-error column.

0.4.1 – 0.4.3

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

0.4.0

0.3.0

Webhooks

A freshly scaffolded app registers the webhooks plugin. An app scaffolded before the plugin existed does not gain it by bumping the version: install @apograph/webhooks-server and @apograph/webhooks-admin at the set’s version, add WebhooksPlugin() to plugins.ts and to the admin’s plugin list, and run npx apograph migrate — it owns three tables.

@apograph/copilot-provider-fake is no longer published. A deployment that registered it as an offline fallback must configure a real backend or leave 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.