84 lines
3.3 KiB
Markdown
84 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](https://www.github.com/nrwl/nx/issues/new/).
|
|
If an update fails for any reason, you can revert it as you do any other set of changes:
|
|
|
|
```bash
|
|
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.
|