Upgrading - Synthetiq Docs

The App Framework is versioned and ships migration guides with each release. These guides are bundled inside the @synthetiq/app-framework package at versions/*.md and document every change, migration step, and new feature for each version.

Version documents

Each version document includes a changelog and any required migration steps. The complexity varies by release type:

Release type	What to expect
Patch (e.g., 1.0.1)	Bug fixes — typically no migration required
Minor (e.g., 1.1.0)	New features with optional migration steps to enable them
Major (e.g., 2.0.0)	Breaking changes with detailed step-by-step migration guides

Upgrade process

Check the currently installed version:

cat node_modules/@synthetiq/app-framework/package.json | grep version

Check the latest available version:

npm view @synthetiq/app-framework version --registry https://api.synthetiq.com/api/npm/

Update the package:

pnpm update @synthetiq/app-framework

List the available version documents:

ls node_modules/@synthetiq/app-framework/versions/

Read and follow all version documents between your old and new version, in order. For example, if upgrading from 1.3.4 to 2.1.0, read every version file from 1.4.0.md through 2.1.0.md and apply each migration step sequentially.
Rebuild the app:

pnpm run build

It is critical to follow all migration guides between your old and new version sequentially. Skipping a version document may result in missing schema changes, configuration updates, or breaking changes.

Workflows worker

For App Framework v2.0 and later, the @synthetiq/workflows-worker package must be installed and its version must exactly match @synthetiq/app-framework. Always update both packages together:

pnpm update @synthetiq/app-framework @synthetiq/workflows-worker

Pre-framework migration

Apps built before the App Framework was introduced can migrate using the pre-framework.md guide bundled in the package at node_modules/@synthetiq/app-framework/versions/pre-framework.md.