Getting started
Nx Cloud
Nx Consulting

Updating Nx

Nx provides migrations which help you stay up to date with the latest version of Nx.

Not only do we migrate the version of Nx, but we also update the versions of dependencies which we install such as jest and cypress.

We recommend waiting for Nx to update these dependencies for you as we verify that these versions work together.

How to Migrate

Generate migrations.json

All you you have to do to update Nx to the latest version is run the following:

nx migrate @nrwl/workspace
nx migrate @nrwl/workspace@version # you can also specify version

This will fetch the specified version of @nrwl/workspace, analyze the dependencies and fetch all the dependent packages. The process will keep going until the whole tree of dependencies is resolved. This will result in:

  • package.json being updated
  • migrations.json being generated

At this point, no packages have been installed, and no other files have been touched.

Now, you can inspect package.json to see if the changes make sense and install the packages by running npm install or yarn.

Run Migrations

migrations.json contains the transformations that must run to prepare the workspace to the newly installed versions of packages. To run all the migrations, invoke:

nx migrate --run-migrations=migrations.json

For small projects, running all the migrations at once often succeeds without any issues.

For large projects, more flexibility is often needed:

  • You may have to skip a migration.
  • You may want to run one migration at a time to address minor issues.
  • You may want to reorder migrations.
  • You may want to run the same migration multiple time if the process takes a long time and you had to rebase.

Since you can run nx migrate --run-migrations=migrations.json as many times as you want, you can achieve all of that by commenting out and reordering items in migrations.json.

The migrate process can take a long time, sometimes day, so it can be useful to commit the migrations file.

Overriding versions

Sometimes, you may want to use a different version of a package than what Nx recommends. You can do it as follows:

nx migrate @nrwl/workspace --to="jest@22.0.0,cypress:3.4.0"

By default, Nx uses currently installed packages to calculate what migrations need to run. You can override them like this:

nx migrate @nrwl/workspace --to="@nrwl/jest@8.0.0"

Reverting a failed update

Updates are best done on a clean git history so that it can be easily reversed if something fails. We try our best to make sure migrations do not fail but if one does, please report it on Github. If an update fails for any reason, you can revert it as you do any other set of changes:

git reset --hard # Reset any changes
git clean -fd # Delete newly added files and directories

Updating Other Dependencies

Nx does not handle updating the dependencies that Nx did not add. Please refer to those projects for the best updating strategy.

Using Angular CLI Update

The nx migrate command uses the same migrations as ng update. You can use either command to update your workspace.

The difference is that nx migrate gives you a lot more control over what gets installed, what migrations run, etc.. This is often needed for mid-size or large projects, where ng-update falls short.