miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs(core): update nx migrate guide (#6155)

Browse Source
This commit is contained in:
Brandon 2021-06-28 09:37:46 -05:00 committed by GitHub
parent 7c7191a2f9
commit 6d32604a05
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 83 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
docs/angular/guides/update.md
View File

@ -1,23 +1,23 @@
# Updating Nx
Nx provides the `migrate` command which help you stay up to date with the latest version of Nx.
The Nx CLI provides the `migrate` command to help you stay up to date with the latest version of Nx.
Not only `nx migrate` updates the version of Nx, but it also updates the versions of dependencies which we install such as jest and cypress. You can also use the `migrate` command to update any Nx plugin or any Angular package.
Not only does `nx migrate` update you to the latest version of Nx, but it also updates the versions of dependencies that we support and test such as Jest and Cypress. You can also use the `migrate` command to update any Nx plugin.
## What About "Ng Update?"
## What about "ng update?"
**TLDR: So if you are using Nx 10, run `nx migrate latest` instead of `ng update`.**
**TLDR: So if you are using Nx 10 or later, run `nx migrate latest` instead of `ng update`.**
If you haven't used Nx before and used the Angular CLI, you probably ran `ng update`. What is the difference?
`nx migrate` is a much improved version of `ng update`. It runs the same migrations, but allows you to:
- rerun the same migration multiple times
- reorder migrations
- skip migrations
- fix migrations that "almost work"
- commit a partially migrated state
- change versions of packages to match org requirements
- Rerun the same migration multiple times.
- Reorder migrations.
- Skip migrations.
- Fix migrations that "almost work".
- Commit a partially migrated state.
- Change versions of packages to match org requirements.
And, in general, it is lot more reliable for non-trivial workspaces. Why?
@ -44,16 +44,16 @@ If you ran `ng update` and saw the error telling you to use `nx migrate`, do the
- `npm install` (or `yarn install`)
- `nx migrate --run-migrations=migrations.json`
## How to Migrate
## Migrating to the latest Nx version
Migration happens in two steps:
- Updating `package.json` (and `node_modules`)
- Updating the source code of the repo to match the new versions of packages in `package.json`
- The installed dependencies are updated including the `package.json` (and `node_modules`).
- The source code in the repo is updated to match the new versions of packages in `package.json`.
### Step 1: Updating package.json and generating migrations.json
### Step 1: Updating dependencies and generating migrations
Run the following:
First, run the `migrate` command:
```bash
nx migrate latest # same as nx migrate @nrwl/workspace@latest
@ -65,75 +65,81 @@ You can also specify the name of the package and the version:
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:
This fetches the specified version of the `@nrwl/workspace` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in:
- `package.json` being updated
- `migrations.json` being generated
- The `package.json` being updated
- A `migrations.json` being generated if there are pending migrations.
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. Sometimes the migration can update some package to the version that is either not allowed or conflicts with with another package. Feel free to manually apply the desired adjustments.
Now, you can inspect `package.json` to see if the changes make sense. Sometimes the migration can update some package to the version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments.
### Step 2: Install the packages
After you are satisfied, make sure to actuall install the packages by running `npm install`, `yarn`, or `pnpm install`.
After inspecting the `package.json`, make sure to install the updated package versions by running `npm install`, `yarn`, or `pnpm install`.
### Step 3: Running migrations
Next, we need to update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During Step 1 Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations.
Next, update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During step one, Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations.
Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, invoke:
Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, run the following command:
```bash
nx migrate --run-migrations
```
To specify a custom migrations file, pass it to the `--run-migrations` option:
```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 sometimes needed:
For small projects, running all the migrations at once often succeeds without any issues. For large projects, more flexibility is 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 a day, so it can be useful to commit the migrations file with the partially-updated repo.
Because you can run `nx migrate --run-migrations` as many times as you want, you can achieve all of that by commenting out and reordering items in `migrations.json`. The migration process can take a long time, depending on the number of migrations, so it is useful to commit the migrations file with the partially-updated repo.
### Step 4: Cleaning up
After you run all the migrations, you can remove `migration.json` and commit the changes.
After you run all the migrations, you can remove `migrations.json` and commit the changes.
## Advanced Capabilities & Recommendations
## Advanced capabilities & recommendations
### One Major Version at a Time, Small Steps
### One major version at a time, small steps
Migrating Jest, Cypress, ESLint, React, Angular, Next etc... is a difficult task. All the tools change at different rates, they can conflict with each other etc.. In addition, every workspace is different. Even though our goal is to let you update any version of Nx to any other version in a single go, sometimes it doesn't work. The following process is better for large workspaces.
Migrating Jest, Cypress, ESLint, React, Angular, Next, and more is a difficult task. All the tools change at different rates, they can conflict with each other. In addition, every workspace is different. Even though our goal is for you to update any version of Nx to a newer version of Nx in a single go, sometimes it doesn't work. The following process is better for large workspaces.
Say you want to migrate from Nx 10.1.0 to Nx 11.0.1. The following steps are more likely to work comparing to `nx migrate 11.0.1`.
- Run `nx migrate 10.4.5` to update the latest version in the 10x branch.
- Run `npm install`
- Run `nx migrate --run-migrations=migrations.json`
- Next, run `nx migrate 11.0.1`
- Run `npm install`
- Run `nx migrate --run-migrations=migrations.json`
- Run `nx migrate 10.4.5` to update the latest version in the 10.x branch.
- Run `npm install`.
- Run `nx migrate --run-migrations`.
- Next, run `nx migrate 11.0.1`.
- Run `npm install`.
- Run `nx migrate --run-migrations`.
### Overriding versions
Sometimes, you may want to use a different version of a package than what Nx recommends. You can do it as follows:
Sometimes, you may want to use a different version of a package than what Nx recommends. To do that, specify the package and version:
```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:
By default, Nx uses currently installed packages to calculate what migrations need to run. To override them, override the version:
```bash
nx migrate @nrwl/workspace --to="@nrwl/jest@8.0.0"
nx migrate @nrwl/workspace --to="@nrwl/jest@12.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/).
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

2
docs/map.json
View File

@ -1239,7 +1239,7 @@
{
"name": "Updating Nx",
"id": "updating-nx",
"file": "angular/guides/update"
"file": "shared/update"
},
{
"name": "Configuration",

68
docs/shared/update.md
View File

@ -1,19 +1,19 @@
# Updating Nx
Nx provides the `migrate` command which help you stay up to date with the latest version of Nx.
The Nx CLI provides the `migrate` command to help you stay up to date with the latest version of Nx.
Not only `nx migrate` updates the version of Nx, but it also updates the versions of dependencies which we install such as jest and cypress. You can also use the `migrate` command to update any Nx plugin.
Not only does `nx migrate` update you to the latest version of Nx, but it also updates the versions of dependencies that we support and test such as Jest and Cypress. You can also use the `migrate` command to update any Nx plugin.
## How to Migrate
## Migrating to the latest Nx version
Migration happens in two steps:
- Updating `package.json` (and `node_modules`)
- Updating the source code of the repo to match the new versions of packages in `package.json`
- The installed dependencies are updated including the `package.json` (and `node_modules`).
- The source code in the repo is updated to match the new versions of packages in `package.json`.
### Step 1: Updating package.json and generating migrations.json
### Step 1: Updating dependencies and generating migrations
Run the following:
First, run the `migrate` command:
```bash
nx migrate latest # same as nx migrate @nrwl/workspace@latest
@ -25,75 +25,81 @@ You can also specify the name of the package and the version:
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:
This fetches the specified version of the `@nrwl/workspace` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in:
- `package.json` being updated
- `migrations.json` being generated
- The `package.json` being updated
- A `migrations.json` being generated if there are pending migrations.
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. Sometimes the migration can update some package to the version that is either not allowed or conflicts with with another package. Feel free to manually apply the desired adjustments.
Now, you can inspect `package.json` to see if the changes make sense. Sometimes the migration can update some package to the version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments.
### Step 2: Install the packages
After you are satisfied, make sure to actuall install the packages by running `npm install`, `yarn`, or `pnpm install`.
After inspecting the `package.json`, make sure to install the updated package versions by running `npm install`, `yarn`, or `pnpm install`.
### Step 3: Running migrations
Next, we need to update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During Step 1 Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations.
Next, update the repo to match the updated `package.json` and `node_modules`. Every Nx plugin comes with a set of migrations that describe how to update the workspace to make it work with the new version of the plugin. During step one, Nx looked at all of the packages being updated and collected their migrations into `migrations.json`. It's important to note that because Nx knows the from and to versions of every package, the `migrations.json` file only contains the relevant migrations.
Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, invoke:
Each migration in `migrations.json` updates the source code in the repository. To run all the migrations in order, run the following command:
```bash
nx migrate --run-migrations
```
To specify a custom migrations file, pass it to the `--run-migrations` option:
```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 sometimes needed:
For small projects, running all the migrations at once often succeeds without any issues. For large projects, more flexibility is 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 a day, so it can be useful to commit the migrations file with the partially-updated repo.
Because you can run `nx migrate --run-migrations` as many times as you want, you can achieve all of that by commenting out and reordering items in `migrations.json`. The migration process can take a long time, depending on the number of migrations, so it is useful to commit the migrations file with the partially-updated repo.
### Step 4: Cleaning up
After you run all the migrations, you can remove `migration.json` and commit the changes.
After you run all the migrations, you can remove `migrations.json` and commit the changes.
## Advanced Capabilities & Recommendations
## Advanced capabilities & recommendations
### One Major Version at a Time, Small Steps
### One major version at a time, small steps
Migrating Jest, Cypress, ESLint, React, Angular, Next etc... is a difficult task. All the tools change at different rates, they can conflict with each other etc.. In addition, every workspace is different. Even though our goal is to let you update any version of Nx to any other version in a single go, sometimes it doesn't work. The following process is better for large workspaces.
Migrating Jest, Cypress, ESLint, React, Angular, Next, and more is a difficult task. All the tools change at different rates, they can conflict with each other. In addition, every workspace is different. Even though our goal is for you to update any version of Nx to a newer version of Nx in a single go, sometimes it doesn't work. The following process is better for large workspaces.
Say you want to migrate from Nx 10.1.0 to Nx 11.0.1. The following steps are more likely to work comparing to `nx migrate 11.0.1`.
- Run `nx migrate 10.4.5` to update the latest version in the 10x branch.
- Run `npm install`
- Run `nx migrate --run-migrations=migrations.json`
- Next, run `nx migrate 11.0.1`
- Run `npm install`
- Run `nx migrate --run-migrations=migrations.json`
- Run `nx migrate 10.4.5` to update the latest version in the 10.x branch.
- Run `npm install`.
- Run `nx migrate --run-migrations`.
- Next, run `nx migrate 11.0.1`.
- Run `npm install`.
- Run `nx migrate --run-migrations`.
### Overriding versions
Sometimes, you may want to use a different version of a package than what Nx recommends. You can do it as follows:
Sometimes, you may want to use a different version of a package than what Nx recommends. To do that, specify the package and version:
```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:
By default, Nx uses currently installed packages to calculate what migrations need to run. To override them, override the version:
```bash
nx migrate @nrwl/workspace --to="@nrwl/jest@8.0.0"
nx migrate @nrwl/workspace --to="@nrwl/jest@12.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/).
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