Nx Migration Generator

Nx PluginにNx Migrationを追加します。Migrationを使用すると、破壊的変更（ターゲットの名前変更、提供される設定の変更、またはコード変更を伴う依存関係のバージョンアップなど）を行った際に、nx migrateがプラグインの以前のバージョンで生成されたプロジェクトを自動的に更新できます。

このジェネレーターは、マイグレーションのスキャフォールディングを行い、プラグインのmigrations.jsonに登録し、プラグインのpackage.jsonにnx-migrationsフィールドを設定します（存在しない場合は両方とも作成します）。

推奨セットアップ

マイグレーション用のベースプロジェクトとしてts#nx-pluginジェネレーターを使用することをお勧めします。これは、ジェネレーターとマイグレーションを公開するように設定されたプラグインプロジェクトを構成します。

使用方法

Migrationの生成

VSCode

1. インストール Nx Console VSCode Plugin まだインストールしていない場合
2. VSCodeでNxコンソールを開く
3. クリック Generate (UI) "Common Nx Commands"セクションで
4. 検索 @aws/nx-plugin - ts#nx-migration
5. 必須パラメータを入力
6. クリック Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-migration

yarn

yarn nx g @aws/nx-plugin:ts#nx-migration

npm

npx nx g @aws/nx-plugin:ts#nx-migration

bun

bunx nx g @aws/nx-plugin:ts#nx-migration

変更されるファイルを確認するためにドライランを実行することもできます

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-migration --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-migration --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-migration --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-migration --dry-run

オプション

パラメータ	型	デフォルト	説明
project 必須	string	-	マイグレーションを追加するNx Pluginプロジェクト。ts#nx-pluginジェネレーターを使用して作成することを推奨します。
name 必須	string	-	マイグレーション名、kebab-case形式で指定（例：rename-foo-target）
description	string	-	マイグレーションが何を行うかの説明。nx migrateコマンドで表示されます
kind	deterministic | agentic | hybrid	deterministic	マイグレーションの種類：deterministic（コードモッド）、agentic（ユーザー所有コードに対するAI適用プロンプト）、またはhybrid（機械的な部分を処理した後、エージェントに引き継ぐコードモッド）
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

3種類のマイグレーション

マイグレーションには3つの形式があり、migrations.jsonエントリが持つフィールドによって区別されます。--kindを渡して選択します（デフォルトはdeterministic）：

• Deterministic（implementation）— 正確な変更前/変更後を持つコードモッド。CI や非対話型ターミナルを含む無人環境で実行されます。これが推奨される種類です：ターゲットファイルがジェネレーターが完全に所有するものであり、編集を機械的に表現できる場合は、常にこれを優先してください。
• Agentic（prompt）— Nxのエージェント型nx migrateフローを介してユーザーのローカルコーディングエージェントによって適用されるマークダウン命令ファイル。ユーザーが所有するコードへの変更で、正しい編集がユーザーが構築したものに依存する場合に使用します。エージェントが実行されない場合（CI、エージェント未インストール、同意拒否）、Nxはプロンプトを手動の指示として表示します。そのため、プロンプトは自己完結型で人間が実行可能なステップとして記述してください。
• Hybrid（implementation + prompt）— 機械的な部分と判断が必要な部分を持つ1つの破壊的変更。implementationは所有するすべてを決定論的に実行し、変更またはスキップした内容を説明するagentContextを返します。Nxはそのコンテキストをペアのpromptに渡し、エージェントをユーザー所有の呼び出し箇所に誘導します。

ジェネレーターの出力

ジェネレーターは、選択したkindに応じて、プラグインプロジェクトのソースフォルダー配下に以下のファイルを作成します：

• Directorysrc/migrations/latest/<name>/

  • migration.ts コードモッドの実装（deterministicとhybrid）
  • migration.spec.ts マイグレーションのテスト（deterministicとhybrid）
  • prompt.md エージェント/人間向けの指示（agenticとhybrid）
• migrations.json マイグレーションを登録するために作成または更新
• package.json “nx-migrations”エントリを追加するために作成または更新

新しいマイグレーションはlatest/に配置されます。マイグレーションをそれを含むリリースごとにグループ化することで、コレクションが増えてもその順序が一目でわかります。バージョンを割り当てる際には、マイグレーションをv<x.y.z>/フォルダーに移動し（migrations.json内のパスを更新）してください。

マイグレーションは、その種類のフィールドとversionなしでmigrations.jsonに登録されます。詳細は下記のバージョニングを参照してください。登録されるキーは、マイグレーションが存在するフォルダーでプレフィックスされます（latest-<name>）。これにより、後の変更で同じ名前を再利用しても、既に出荷されたマイグレーションが誤って上書きされることはありません。

Migrationの実装

deterministic（またはhybrid）マイグレーションは、仮想ファイルシステム（Tree）を変更し、MigrationReturnObjectを返す関数です。以下は両方を返すhybridの例です：

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 — nx migrate実行後にユーザーに表示されるワークスペース全体のメモ。スキップしたファイル（下記のガードレールを参照）や、マイグレーションが実行できなかった手動フォローアップを報告するために使用します。
• agentContext（hybridのみ）— コードモッドが変更した内容の要約。Nxのエージェント型フローで実行される際にペアのpromptに渡され、エージェントがユーザー所有の部分に集中できるようにします。

ジェネレーターで使用するのと同じ操作（generateFiles、GritQL変換、JSONの読み取りと更新）については、Nx Generatorガイドを参照してください。

ガードレール

マイグレーションは制御できないワークスペースに対して実行されるため、スキャフォールディングされたスケルトンに組み込まれているのと同じルールに従ってください：

• 書き込む前にパターンマッチ。 ターゲットファイルがジェネレーターが生成する形状から逸脱している場合は、ユーザーの変更を上書きするのではなく、スキップしてnextSteps経由で報告します。
• 冪等性。 マイグレーションの再実行は何も行わない必要があります。
• 書き込んだファイルをフォーマットする。 formatFilesInSubtree(tree)で締めくくり、マイグレーションが書き込んだファイルが正しくフォーマットされるようにします。

Migrationのテスト

スキャフォールディングされたmigration.spec.tsは、createTreeUsingTsSolutionSetup()を使用して、プリセットが生成する形状に一致する仮想ワークスペースを構築します。マイグレーションがワークスペースを「変更前」の状態からターゲット状態に移行し、認識できないコードをスキップ（および報告）し、冪等であることをテストします：

import type { Tree } from '@nx/devkit';
import { createTreeUsingTsSolutionSetup } from '@aws/nx-plugin/sdk/utils/test';
import migration from './migration';

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');
  });
});

バージョニング

Nxは、ユーザーがインストールしているプラグインのバージョンがマイグレーションのversionより低い場合にマイグレーションを実行します。このジェネレーターはversionフィールドを書き込みません。マイグレーションを含むリリースをカットする際に割り当てる（またはリリースプロセスからスタンプする）ことで、以前のバージョンからアップグレードするすべてのユーザーに対して実行されます。

バージョンを割り当てると、各種類のマイグレーションを1つずつ登録するmigrations.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"
    }
  }
}

Migrationの実行

ユーザーは、2ステップのnx migrateフローでプラグインのマイグレーションを適用します。保留中のマイグレーションを生成し、インストールしてから実行します：

pnpm

pnpm nx migrate my-plugin@latest
pnpm nx migrate --run-migrations

yarn

yarn nx migrate my-plugin@latest
yarn nx migrate --run-migrations

npm

npx nx migrate my-plugin@latest
npx nx migrate --run-migrations

bun

bunx nx migrate my-plugin@latest
bunx nx migrate --run-migrations

Agenticおよびhybridマイグレーションは、利用可能な場合、nx migrate --run-migrationsの実行中にユーザーのローカルコーディングエージェントによって適用されます。

アップグレードするユーザーの視点からの完全なフロー（deterministicおよびagenticマイグレーションの出力例を含む）については、ワークスペースのアップグレードを参照してください。 grade-framework/prompt.md” } } }

## Migrationの実行

ユーザーは、2ステップの`nx migrate`フローでプラグインのマイグレーションを適用します。保留中のマイグレーションを生成し、インストールしてから実行します：

<NxCommands commands={['migrate my-plugin@latest', 'migrate --run-migrations']} />

Agenticおよびhybridマイグレーションは、利用可能な場合、`nx migrate --run-migrations`の実行中にユーザーのローカルコーディングエージェントによって適用されます。

アップグレードするユーザーの視点からの完全なフロー（deterministicおよびagenticマイグレーションの出力例を含む）については、<Link path="get_started/upgrading">ワークスペースのアップグレード</Link>を参照してください。