8fa7065cf1
This PR updates examples in `.md` files (both docs and blog posts) to use positional args. Nx 20 changes the position arg to be either `directory` for apps/libs or `path` for artifacts (e.g. components). So before you'd do this: ``` nx g app myapp --directory=apps/myapp nx g lib mylib --directory=libs/mylib nx g lib mylib --directory=libs/nested/mylib nx g lib @acme/foo --directory=libs/@acme/foo --importPath=@acme/foo nx g component foo --directory=libs/ui/src/foo --pascalCaseFiles ``` Will now be simplified to ``` nx g app apps/myapp nx g lib libs/mylib nx g lib libs/nested/mylib nx g lib libs/@acme/foo # name and import path are both "@acme/foo" nx g component libs/ui/src/foo/Foo ``` For cases where `name` and `importPath` need to be changed, you can always manually specify them. ``` nx g lib libs/nested/foo # name is foo nx g lib libs/nested/foo --name=nested-foo # specify name with prefix nx g lib libs/@acme/foo --name # use "foo" as name and don't match importPath nx g lib libs/@internal/foo --importPath=@acme/foo # different importPath from name <!-- If this is a particularly complex change or feature addition, you can request a dedicated Nx release for this pull request branch. Mention someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they will confirm if the PR warrants its own release for testing purposes, and generate it for you if appropriate. --> ## Current Behavior <!-- This is the behavior we have today --> ## Expected Behavior <!-- This is the behavior we should expect with the changes in this PR --> ## Related Issue(s) <!-- Please link the issue being fixed so it gets closed when this is merged. --> Fixes #
91 lines
2.8 KiB
Markdown
91 lines
2.8 KiB
Markdown
# Migration Generators
|
|
|
|
When your plugin is being used in other repos, it is helpful to provide migration generators to automatically update configuration files when your plugin makes a breaking change.
|
|
|
|
A migration generator is a normal generator that is triggered when a developer runs the `nx migrate` command.
|
|
|
|
## Create a Migration Generator
|
|
|
|
For this example, we'll create a new migration generator that updates repos to use `newExecutorName` instead of `oldExecutorName` in their targets. This migration will be applied when the run `nx migrate` to move up past version `2.0.1` of our plugin.
|
|
|
|
### 1. Generate a migration
|
|
|
|
```shell
|
|
nx generate @nx/plugin:migration libs/pluginName/src/migrations/change-executor-name \
|
|
--name='Change Executor Name' \
|
|
--packageVersion=2.0.1 \
|
|
--project=pluginName \
|
|
--description='Changes the executor name from oldExecutorName to newExecutorName'
|
|
```
|
|
|
|
This command will update the following files:
|
|
|
|
```json {% fileName="package.json" %}
|
|
{
|
|
"nx-migrations": {
|
|
"migrations": "./migrations.json"
|
|
}
|
|
}
|
|
```
|
|
|
|
```json {% fileName="migrations.json" %}
|
|
{
|
|
"generators": {
|
|
"change-executor-name": {
|
|
"version": "2.0.1",
|
|
"description": "Changes the executor name from oldExecutorName to newExecutorName",
|
|
"cli": "nx",
|
|
"implementation": "./src/migrations/change-executor-name/change-executor-name"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
And it creates a blank generator under: `libs/pluginName/src/migrations/change-executor-name/change-executor-name.ts`
|
|
|
|
### 2. Write the Generator Code
|
|
|
|
```ts {% fileName="change-executor-name.ts" %}
|
|
import { getProjects, Tree, updateProjectConfiguration } from '@nx/devkit';
|
|
|
|
export function changeExecutorNameToNewName(tree: Tree) {
|
|
const projects = getProjects(tree);
|
|
|
|
for (const [name, project] of projects) {
|
|
if (
|
|
project.targets?.build?.executor === '@myorg/pluginName:oldExecutorName'
|
|
) {
|
|
project.targets.build.executor = '@myorg/pluginName:newExecutorName';
|
|
updateProjectConfiguration(tree, name, project);
|
|
}
|
|
}
|
|
}
|
|
|
|
export default changeExecutorNameToNewName;
|
|
```
|
|
|
|
## Update package.json dependencies
|
|
|
|
If you just need to change dependency versions, you can add some configuration options to the `migrations.json` file without making a full generator.
|
|
|
|
```json {% fileName="migrations.json" %}
|
|
{
|
|
"packageJsonUpdates": {
|
|
// this can be any name
|
|
"12.10.0": {
|
|
// this is version at which the change will be applied
|
|
"version": "12.10.0-beta.2",
|
|
"packages": {
|
|
// the name of the dependency to update
|
|
"@testing-library/react": {
|
|
// the version to set the dependency to
|
|
"version": "11.2.6",
|
|
// When true, the dependency will be added if it isn't there. When false, the dependency is skipped if it isn't already present.
|
|
"alwaysAddToPackageJson": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|