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

docs(core): update nx migrate feature page

Browse Source
This commit is contained in:
Juri 2024-07-31 17:19:02 +02:00 committed by Juri Strumpflohner
parent e0c0548f5e
commit 2ce679755f
2 changed files with 62 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
docs/shared/features/automate-updating-dependencies.md
View File

@ -1,38 +1,61 @@
# Automate Updating Dependencies
Keeping a codebase updated with the latest changes in your framework of choice can be challenging. Not to mention that "tooling maintenance work" is usually hard to squeeze into your feature sprint.
Keeping your tooling up to date is crucial for the health of your project. Tooling maintenance work can be tedious and time consuming, though. The **Nx migrate** functionality provides a way for you to
## nx migrate Makes Updating Simple
The `nx migrate` command helps by automating the process of updating:
- package versions in your `package.json`
- configuration files (e.g. your Jest, ESLint or Nx config)
- your source code (e.g. fixing breaking changes or migrating to new best practices)
## How Does It Work?
- automatically update your **`package.json` dependencies**
- migrate your **configuration files** (e.g. Jest, ESLint, Nx config)
- **adjust your source code** to match the new versions of packages (e.g., migrating across breaking changes)
{% youtube
src="https://www.youtube.com/embed/Ss6MfcXi0jE"
title="How Automated Code Migrations Work"
/%}
Nx knows where its configuration files are and can therefore make sure they match the expected format. This automated update process, commonly referred to as "migration," becomes even more powerful when you leverage [Nx plugins](/nx-api). Nx plugins, which are NPM packages with a range of capabilities (code generation, task automation...), offer targeted updates based on their specific areas of responsibility.
To update your workspace, run:
For example, the [Nx ESLint plugin](/nx-api/eslint) excels at configuring linting in your workspace. With its understanding of the configuration file locations, this plugin can provide precise migration scripts to update ESLint packages in your `package.json` and corresponding configuration files in your workspace when a new version is released.
```shell
npx nx migrate latest
```
Updating happens in three steps:
## How Does It Work?
- 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 according to the set of instructions specified in `migrations.json` file.
- Optionally remove the `migrations.json` file or keep it to re-run the migration in different Git branches
Nx knows where its configuration files are located and ensures they match the expected format. This automated update process, commonly referred to as "migration," becomes even **more powerful when you leverage [Nx plugins](/nx-api)**. Each plugin can provide migrations for its area of competency.
### Step 1: Update Dependencies and Generating Migrations
For example, the [Nx React plugin](/nx-api/react) knows where to look for React and Nx specific configuration files and knows how to apply certain changes when updating to a given version of React.
In the example below, the React plugin defines a migration script (`./src/migrations/.../add-babel-core`) that runs when upgrading to Nx `16.7.0-beta.2` (or higher).
```json {% fileName="migrations.json" highlightLines=[6,7] %}
{
"generators": {
...
"add-babel-core": {
...
"version": "16.7.0-beta.2",
"implementation": "./src/migrations/update-16-7-0/add-babel-core"
},
},
}
```
When running `nx migrate latest`, Nx parses all the available plugins and their migration files and applies the necessary changes to your workspace.
## How Do I Upgrade My Nx Workspace?
Updating your Nx workspace happens in three steps:
1. The **installed dependencies**, including the `package.json` and `node_modules`, are updated.
2. Nx produces a `migrations.json` file containing the **migrations to be run** based on your workspace configuration. You can inspect and adjust the file. Run the migrations to update your configuration files and source code.
3. Optionally, you can remove the `migrations.json` file or keep it to re-run the migration in different Git branches.
You can intervene at each step and make adjustments as needed for your specific workspaces. This is especially important in large codebases where you might want to control the changes more granularly.
### Step 1: Update Dependencies and Generate Migrations
First, run the `migrate` command:
```shell
nx migrate latest # same as nx migrate nx@latest
nx migrate latest
```
Note you can also specify an exact version by replacing `latest` with `nx@<version>`.
@ -41,23 +64,14 @@ Note you can also specify an exact version by replacing `latest` with `nx@<versi
To avoid potential issues, it is [recommended to update one major version of Nx at a time](/recipes/tips-n-tricks/advanced-update#one-major-version-at-a-time-small-steps).
{% /callout %}
This fetches the specified version of the `nx` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in:
This results in:
- The `package.json` being updated
- A `migrations.json` being generated if there are pending migrations.
{% callout type="note" title="Dependency Updates" %}
The migrations will update the `@nx/*` packages to the desired version. Subsequently, these packages _may_ also update other dependencies in your `package.json` to new versions if support has been added for them.
For example, migrating `@nx/react` to the latest version may also update the `react` version if support has been added for the latest version.
{% /callout %}
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 a package to a version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments.
{% callout type="note" title="Inspect the changes" %}
At this stage, after inspecting the `package.json`, you may wish to manually run the appropriate install command for your workspace (e.g. `npm install`, `yarn`, or `pnpm install`) but in the next step `nx migrate --run-migrations` will also run this automatically for you.
{% /callout %}
Now, you can **inspect `package.json` to see if the changes make sense**. Sometimes the migration can update a package to a version that is either not allowed or conflicts with another package. Feel free to manually apply the desired adjustments. Also look at the `migrations.json` for the type of migrations that are going to be applied.
### Step 2: Run Migrations
@ -67,9 +81,11 @@ You can now run the actual code migrations that were generated in the `migration
nx migrate --run-migrations
```
This will update your source code in your workspace in accordance with the implementation of the various migrations which ran and all the changes will be unstaged ready for you to review and commit yourself.
Depending on the migrations that ran, this might **update your source code** and **configuration files** in your workspace. All the changes will be unstaged ready for you to review and commit yourself.
{% callout type="info" title="Migrations are version specific" %}
Note that each Nx plugin is able to provide a set of migrations which are relevant to particular versions of the package. Hence `migrations.json` will only contain migrations which are appropriate for the update you are currently applying.
{% /callout %}
### Step 3: Clean Up
@ -77,17 +93,9 @@ After you run all the migrations, you can remove `migrations.json` and commit an
Note: You may want to keep the `migrations.json` until every branch that was created before the migration has been merged. Leaving the `migrations.json` in place allows devs to run `nx migrate --run-migrations` to apply the same migration process to their newly merged code as well.
## Keep Nx Packages on the Same Version
### Step 4: Update Community Plugins (Optional)
When you run `nx migrate`, the `nx` package and all the `@nx/` packages get updated to the same version. It is important to [keep these versions in sync](/recipes/tips-n-tricks/keep-nx-versions-in-sync), or you can encounter some difficult to debug errors. As long as you run `nx migrate` instead of manually changing the version numbers, you shouldn't have to worry about it. Also, when you add a new plugin, use `nx add <plugin>` to automatically install the version that matches your repository's version of Nx.
{% callout type="note" title="Use the latest nx-cloud version" %}
The `nx-cloud` package does not need to be in sync with the other Nx packages. For best results, stay on the latest version of `nx-cloud`. The latest `nx-cloud` version supports the most recent 2 major versions of `nx`, although earlier versions of `nx` may also be compatible.
{% /callout %}
## Migrate Community Plugins Individually
Community plugins should be migrated individually with:
If you have any [Nx community plugins](/plugin-registry) installed you need to migrate them individually (assuming they provide migration scripts) by using the following command:
```shell
nx migrate my-plugin
@ -99,6 +107,14 @@ For a list of all the plugins you currently have installed, run:
nx report
```
## Keep Nx Packages on the Same Version
When you run `nx migrate`, the `nx` package and all the `@nx/` packages get updated to the same version. It is important to [keep these versions in sync](/recipes/tips-n-tricks/keep-nx-versions-in-sync) to have Nx work properly.
As long as you run `nx migrate` instead of manually changing the version numbers, you shouldn't have to worry about it. Also, when you add a new plugin, use `nx add <plugin>` to automatically install the version that matches your repository's version of Nx.
## Need to Opt-out of Some Migrations?
Sometimes you need to temporarily opt-out from some migrations because your workspace is not ready yet. You can manually adjust the `migrations.json` or run the update with the `--interactive` flag to choose which migrations you accept. Find more details in our [Advanced Update Process](/recipes/tips-n-tricks/advanced-update) guide.
Sometimes you need to temporarily opt-out from some migrations because your workspace is not ready yet. You can manually adjust the `migrations.json` or run the update with the `--interactive` flag to choose which migrations you accept.
Find more details in our [Advanced Update Process](/recipes/tips-n-tricks/advanced-update) guide.

11
nx-dev/nx-dev/pages/nx-api/index.tsx
View File

@ -112,18 +112,17 @@ export default function Packages({
<section id="packages-section" className="py-1">
<p>
In version 16, we have rescoped our packages to{' '}
<code>@nx/*</code> from <code>@nrwl/*</code>.{' '}
Read more about what Nx plugins are on our{' '}
<Link
href="/recipes/other/rescope"
className="underline"
href="/concepts/nx-plugins"
className="text-blue-600 transition-colors ease-out hover:text-blue-700 dark:text-sky-500 dark:hover:text-sky-400"
prefetch={false}
>
Read more about the rescope ≫
docs page.
</Link>
</p>
</section>
<section id="packages-section" className="py-12">
<section id="packages-section" className="py-6">
<nav
aria-labelledby="package-index-navigation"
className="relative mb-24 grid grid-cols-2 gap-4 lg:grid-cols-3 xl:grid-cols-5"