Updating Angular Versions with Nx
When a new version of Angular is released, it is closely followed by a similarly labeled Nx release. Here are a couple things to consider before updating:
-
If you can, wait at least a few weeks after the new Angular version comes out. Nx needs a little while to iron out some bugs that tend to crop up early on.
-
Sometimes it’s helpful to create a fresh new workspace with the same version of Nx that you’re using to update the version of Angular to compare the versions that are being planned to be installed in your application with those that are automatically generated. For example, when updating versions, Nx probably won’t update the version of Cypress. You could just update Cypress to the latest version but there’s a possibility that the latest version of Cypress isn’t yet compatible with the latest version of Angular/Nx
Start the Migration
Make sure you’re on a new branch. Update your global installation of Nx:
Inside your angular application root level, run the first step of the migration. For anyone who needs to update to the most current major version of Angular, run
If you need to update to a specific version of Angular, run
Once done, check out your package.json file. Confirm that most packages starting with @angular and @nrwl have updated to the expected major version.
It’s worth noting that this file will show what versions should be but that the specified package version haven’t been installed yet.
Additionally, you may notice that the process generated a migrations.json file. You should never need to change this file directly so just leave it as is for now.
Next, run the migrations officially which will run the installs.
This will only apply the migrations for core Angular and Nx-related packages. Since these are the most likely to contain “breaking changes” which will be resolved by Nx (if you’re curious about what some of these might be, take a look at the content of the migrations.json - all migrations have descriptions of what will end up being done during the migration we just ran).
It’s important to do this before updating the rest of the updates. When running nx migrate
Once this is done, try serving your application now to make sure that everything compiles and runs the way you expect. Occasionally something may have gone sideways during the migrations so it’s important to give the whole thing a good ol' smoke test to make sure nothing stands out as having broken in the process. Run your linter, try your auto-formatter, run your unit tests… I’ve had issues before with some or all of these things breaking during migration and it’s important to keep them in working order.
If everything looks good at this point, delete the migrations.json, we don’t need it and there’s really no need to check it in.
It is recommended to check in the changes to your development branch thus far. Checkpoint - get. Now if something gets too rowdy after this, it’s easier to just rollback the offending changes.
There will likely be packages that weren’t updated that need to be. Since most likely there aren’t proper migrations that need to happen, install those updates now, such as
Next do a similar process for your development dependencies that may need updates like
Once that’s done and your app seems to be serving and building as expected, linter linting, formatter formatting, and tests running (and hopefully succeeding), commit those changes.
At this point, your update should be done. If you’ve run into issues along the way, please reach out to the Angular Standard team, we’ll do our best to help out!
Other Resources
https://nx.dev/core-features/automate-updating-dependencies
https://nx.dev/recipes/other/advanced-update