Upgrade NX Application to Angular 21

This guide describes how to upgrade an NX-based OneCX application to Angular 21. Complete the pre-migration steps from the main migration guide before you continue.

Update NX and Angular packages

Update your workspace packages by running:

nx migrate latest --interactive

Apply all proposed updates up to Angular 21.

For details on NX / Angular compatibility, refer to the Angular NX Version Matrix.

For details on nx migrate, refer to the official documentation: NX Migrate Documentation.

Update package versions in package.json

  1. Update all used @onecx/* packages to version ^8.0.0.

    Example:
    npm install @onecx/<package-name>@^8

  2. Update the packages listed here to the specified versions: Required Package Updates.

  3. After updating package.json, run npm install to install the new versions. If you see peer dependency errors, update the affected packages to compatible versions.

If you still see dependency conflicts that reference old versions, reinstall dependencies from scratch:

rm -rf node_modules package-lock.json .angular dist ~/.angular/cache && npm cache clean --force && npm install

Make sure to migrate the updated packages and resolve any breaking changes. Refer to the official documentation of each package for migration guides and instructions.

Run NX migration

After updating package versions, run:

nx migrate --run-migrations

After this step, proceed with the remaining post-migration steps.