@aws/nx-plugin-mcp 1.0.0-rc.8 → 1.0.0-rc.80

package/docs/guides/nx-migration.mdx

@@ -0,0 +1,165 @@
+---
+title: Nx Migration Generator
+description: Generates an Nx Migration for an Nx Plugin
+generator: ts#nx-migration
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Link from '@components/link.astro';
+
+Adds an [Nx Migration](https://nx.dev/docs/kb/migration-generators) to an Nx Plugin. Migrations let `nx migrate` automatically update projects that were generated by a previous version of your plugin when you make a breaking change — renamed targets, changed vended config, or a dependency bump that requires accompanying code changes.
+
+The generator scaffolds the migration, registers it in your plugin's `migrations.json`, and wires the `nx-migrations` field into your plugin's `package.json` (creating both if they don't exist yet).
+
+:::tip[Recommended Setup]
+We recommend using the <Link path="/guides/ts-nx-plugin">`ts#nx-plugin`</Link> generator as the base project for your migrations, since it configures a plugin project set up to publish generators and migrations.
+:::
+
+## Usage
+
+### Generate a Migration
+
+<RunGenerator generator="ts#nx-migration" />
+
+### Options
+
+<GeneratorParameters generator="ts#nx-migration" />
+
+## The three kinds of migration
+
+Migrations come in three forms, discriminated by which fields the `migrations.json` entry carries. Pass `--kind` to choose (default `deterministic`):
+
+- **Deterministic** (`implementation`) — a codemod with an exact before/after, and the one to reach for first. It runs unattended, including in CI and non-interactive terminals, and applies identically for every user. Use it alone when the change has a shape you can match reliably everywhere it appears, reporting anything it skipped via `nextSteps`.
+- **Hybrid** (`implementation` + `prompt`) — both halves of one change. Use it when a change is breaking and can't be fully applied mechanically: the codemod does as much as it can safely match and returns `agentContext` describing what it changed *and what it skipped*; Nx passes that context to the paired `prompt`, which directs the agent at the rest. The prompt is what stops a workspace being left broken when the leftover edits span too many shapes to codemod.
+- **Agentic** (`prompt`) — a markdown instruction file applied by the user's local coding agent via Nx's agentic `nx migrate` flow. Use it alone when no mechanical before/after holds at all, because the correct edit depends on what the user has built. When no agent runs (CI, no agent installed, consent declined), Nx surfaces the prompt as manual instructions — so write prompts as self-contained, human-actionable steps.
+
+## Generator Output
+
+The generator creates the following files under your plugin project's source folder, depending on the chosen `kind`:
+
+<FileTree>
+  - src/migrations/latest/\<name>/
+    - migration.ts Codemod implementation (deterministic and hybrid)
+    - migration.spec.ts Tests for your migration (deterministic and hybrid)
+    - prompt.md Agent/human instructions (agentic and hybrid)
+  - migrations.json Created or updated to register your migration
+  - package.json Created or updated to add an "nx-migrations" entry
+</FileTree>
+
+A new migration lands in `latest/`. Grouping migrations by the release that ships them keeps their order visible at a glance as the collection grows — move a migration into a `v<x.y.z>/` folder (and update its paths in `migrations.json`) when you assign its version.
+
+It registers the migration in `migrations.json` with the fields for its kind and no `version` — see [Versioning](#versioning) below. The registered key is prefixed with the folder the migration lives in (`latest-<name>`), so reusing a name for a later change can't silently overwrite a migration that has already shipped.
+
+## Implementing a Migration
+
+A deterministic (or hybrid) migration is a function which mutates the virtual filesystem (the `Tree`), returning a [`MigrationReturnObject`](https://nx.dev/docs/reference/devkit/MigrationReturnObject). Here's a hybrid one, which returns both:
+
+```ts
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';
+
+export default async function migration(
+  tree: Tree,
+): Promise<MigrationReturnObject> {
+  const nextSteps: string[] = [];
+  const agentContext: string[] = [];
+
+  // Read and update the files your generators produce here.
+
+  await formatFilesInSubtree(tree);
+
+  return { nextSteps, agentContext };
+}
+```
+
+- **`nextSteps`** — the follow-up actions Nx prints for the user after `nx migrate` runs. Every entry should be something they need to do by hand: reconcile a file you skipped (see the guardrails below), or finish something beyond the migration's reach, like an install to refresh a lock file. They aren't a log of what you changed — when a transform applies cleanly, add nothing, otherwise the entries that do need action get buried.
+- **`agentContext`** (hybrid only) — a summary of what the codemod changed, passed to the paired `prompt` when it runs under Nx's agentic flow so the agent can focus on the user-owned parts.
+
+For some example operations you can perform in your migration (generating files, modifying existing files using GritQL, reading and updating JSON), refer to the <Link path="/guides/nx-generator">Nx Generator guide</Link>.
+
+### Guardrails
+
+Migrations run against workspaces you don't control, so it is recommended to adhere to the following (the scaffolded skeleton bakes these in):
+
+- **Transform source code with GritQL.** Use the <Link path="/guides/nx-generator">GritQL helpers</Link> (`applyGritQL`, `matchGritQL`) to edit source rather than regexes or string replacements. GritQL matches the AST, so one pattern holds across the formatting, whitespace and quoting a user's copy may have drifted into, where text matching quietly misses equivalent code or corrupts the file. Use `updateJson` for JSON and the matching parser for other structured config.
+- **Pattern-match before writing.** If a target file has diverged from the shape your generators produce, skip it and report it via `nextSteps`, or consider a hybrid migration, rather than clobbering the user's changes. `matchGritQL` is a convenient way to make that check.
+- **Report only what's left to do.** `nextSteps` is for work the user has to pick up, not a record of the edits you made — those are already in their `git diff`.
+- **Idempotent.** Re-running the migration must be a no-op. Guard GritQL rewrites that inject code with a `where { ... <: not contains ... }` clause so a second run doesn't append a duplicate.
+- **Format what you write.** Finish with `formatFilesInSubtree(tree)` so the files your migration wrote are formatted correctly.
+
+### Testing Your Migration
+
+The scaffolded `migration.spec.ts` uses `createTreeUsingTsSolutionSetup()` to build a virtual workspace matching the shape our preset generates. Test that the migration takes a workspace from the "before" state to the target state, skips (and reports) code it doesn't recognise, and is idempotent:
+
+```ts
+import type { Tree } from '@nx/devkit';
+import { createTreeUsingTsSolutionSetup } from '@aws/nx-plugin/sdk/utils/test';
+import migration from './migration.js';
+
+describe('my migration', () => {
+  let tree: Tree;
+
+  beforeEach(() => {
+    tree = createTreeUsingTsSolutionSetup();
+  });
+
+  it('should update the generated shape', async () => {
+    // Set up a tree with the "before" state
+    tree.write('project.json', JSON.stringify({ targets: { foo: {} } }));
+
+    // Run the migration
+    await migration(tree);
+
+    // Check that the tree matches the target state
+    const projectJson = JSON.parse(tree.read('project.json', 'utf-8'));
+    expect(projectJson.targets).toHaveProperty('bar');
+    expect(projectJson.targets).not.toHaveProperty('foo');
+  });
+});
+```
+
+Unit tests only prove the migration does what you wrote it to do. Also test it against a workspace generated by the **published** version of your plugin — the state your users upgrade from — and confirm the result matches what your generators produce today: inspect the diff, generate the same projects into a fresh workspace and compare, check the workspace still builds, then re-run the migration to confirm it changes nothing. Repeat with a workspace you've customised first, to check the migration leaves your edits alone and reports them instead.
+
+## Versioning
+
+Nx runs a migration when the user's installed plugin version is less than the migration's `version`. This generator writes **no** `version` field — assign it (or stamp it from your release process) when you cut the release that ships the migration, so it runs for everyone upgrading from an earlier version.
+
+Once you assign versions, a `migrations.json` registering one migration of each kind looks like this:
+
+```json
+{
+  "$schema": "http://json-schema.org/schema",
+  "name": "my-plugin",
+  "generators": {
+    "v2.0.0-rename-foo-target": {
+      "version": "2.0.0",
+      "description": "Rename the foo target to bar",
+      "implementation": "./src/migrations/v2.0.0/rename-foo-target/migration"
+    },
+    "v3.0.0-migrate-custom-handlers": {
+      "version": "3.0.0",
+      "description": "Update custom handlers for the new API",
+      "prompt": "./src/migrations/v3.0.0/migrate-custom-handlers/prompt.md"
+    },
+    "v4.0.0-upgrade-framework": {
+      "version": "4.0.0",
+      "description": "Upgrade the framework and reconcile call sites",
+      "implementation": "./src/migrations/v4.0.0/upgrade-framework/migration",
+      "prompt": "./src/migrations/v4.0.0/upgrade-framework/prompt.md"
+    }
+  }
+}
+```
+
+## Running Migrations
+
+Users apply your plugin's migrations with the two-step `nx migrate` flow — generate the pending migrations, install, then run them:
+
+<NxCommands commands={['migrate my-plugin@latest', 'migrate --run-migrations']} />
+
+Agentic and hybrid migrations are applied by the user's local coding agent during `nx migrate --run-migrations` when one is available.
+
+For the full flow from the upgrading user's perspective — including example output for deterministic and agentic migrations — see <Link path="get_started/upgrading">Upgrading Your Workspace</Link>.