> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading

> How to upgrade the App Framework and follow version migration guides

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

1. Check the currently installed version:

```bash theme={null}
cat node_modules/@synthetiq/app-framework/package.json | grep version
```

2. Check the latest available version:

```bash theme={null}
npm view @synthetiq/app-framework version --registry https://api.synthetiq.com/api/npm/
```

3. Update the package:

```bash theme={null}
pnpm update @synthetiq/app-framework
```

4. List the available version documents:

```bash theme={null}
ls node_modules/@synthetiq/app-framework/versions/
```

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

6. Rebuild the app:

```bash theme={null}
pnpm run build
```

<Warning>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.</Warning>

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

```bash theme={null}
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`.