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.
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:
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
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
The migrate process can take a long time, sometimes day, so it can be useful to commit the migrations file.
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="firstname.lastname@example.org,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="@email@example.com"
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
Nx does not handle updating the dependencies that Nx did not add. Please refer to those projects for the best updating strategy.
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.