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:
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. 
