既存プロジェクトへの追加

すべてのプロジェクトがpnpm create @aws/nx-workspaceで始まるわけではありません。すでにNxワークスペースを持っている場合、またはNxを追加できるモノレポがある場合は、プロジェクトを再作成することなく@aws/nx-pluginを段階的に導入できます。

前提条件

必須

Git
Node >= 22 (ノードのバージョン管理にはNVMなどの使用を推奨します)
- node --version を実行して確認
PNPM >= 11 (代替としてYarn >= 4、Bun >= 1、またはNPM >= 10も使用可能)
- pnpm --version、yarn --version、bun --version または npm --version を実行して確認
UV >= 0.5.29
1. 以下のコマンドを実行して Python 3.14 をインストール: uv python install 3.14.0
2. uv python list --only-installed でインストール済みバージョンを確認
ターゲットとなるAWSアカウント（アプリケーションをデプロイする環境）に設定されたAWS認証情報

推奨

Dockerは一部のジェネレーターで必要です。マルチプラットフォームビルドをセットアップする必要があります。
CDKの代わりにインフラストラクチャー・アズ・コードでTerraformを使用する場合、Terraform >= 1.12が必要です
- terraform --version を実行して確認してください
VSCodeを使用する場合、Nx Console VSCode Pluginのインストールを推奨します

非NxプロジェクトへのNxの追加

プロジェクトがまだNxを使用していない場合は、まずnx initで追加します。これはNx自体が所有するステップです。プラグインは動作するNxワークスペースの上に構築されます。これは、プレーンパッケージ、npm/pnpm/yarn/bunワークスペース、TurborepoまたはLernaモノレポで動作します。

pnpm dlx nx@23.0.2 init

yarn dlx nx@23.0.2 init

npx nx@23.0.2 init

bunx nx@23.0.2 init

プロンプトに従ってワークスペースにNxを追加してください。詳細については、Nxドキュメントを参照してください。

pnpmは許可リストに載っているパッケージのインストールスクリプトのみを実行し、nxにはそのインストールスクリプトが必要です — それがないと、nx initが実行するインストールが失敗し、pnpm-workspace.yamlにset this to true or falseプレースホルダーが残る可能性があります。nx initを実行する前に許可リストに追加してください。

allowBuilds:
  - nx

非Nodeプロジェクト（Python、Go、Java、Rust、…）

Nxとプラグインはnpmパッケージとして配布されているため、Node.jsツールを持たないプロジェクトは、nx initが何か有用なことをする前に、最小限のルートpackage.jsonが必要です。

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

そのファイルを作成してから、nx initを実行し、通常どおりプラグインを追加します。既存の言語ツールは影響を受けません — プラグインによって生成されたNxプロジェクト（Pythonプロジェクトを含む）は既存のコードと並んで存在し、既存のビルドを段階的にNxに接続できます。

既存のプロジェクトをNxの管理下に置くには、言語に応じていくつかのオプションがあります：

公式のNxプラグインがある言語 — Java（GradleまたはMaven）と.NETには、プロジェクトのタスクを自動的に推論する専用プラグインがあります。関連するものを追加してください。例：nx add @nx/gradle、nx add @nx/maven、またはnx add @nx/dotnet。
コミュニティプラグインがある言語 — 例えばGo（@nx-go/nx-go）やRust（@monodon/rust）。他のものについてはNx Plugin Registryを参照してください。
その他の言語 — 各プロジェクトにproject.jsonを追加し、既存のビルドコマンドを実行するターゲットを定義することで、nx build <project>（およびnx run-many）がそれらを駆動できるようにします。project.jsonとターゲットの設定方法については、ワークスペースガイドを参照してください。

シングルパッケージプロジェクト

プラグインはモノレポ用に設計されています — 各プロジェクトをpackages/の下の独自のディレクトリに生成します。シングルパッケージプロジェクト（ルートに1つのpackage.jsonがあり、その直下にソースがあり、ワークスペースがない）から始める場合は、プラグインを導入する前に既存のパッケージをpackages/に移動して、プロジェクトがプラグインが生成するものと並んで配置されるようにします。

packages/<your-package>/ディレクトリを作成し、ソース、package.json、tsconfig.jsonをそこに移動します。
プロジェクト自体ではなくワークスペースマニフェストとして機能する新しいルートpackage.jsonを作成します：
package.json
```
{
  "name": "<your-workspace>",
  "private": true,
  "type": "module"
}
```
パッケージマネージャーがpackages/の下のプロジェクトを検出できるようにワークスペースを宣言します。pnpmの場合は、pnpm-workspace.yamlを追加します：
pnpm-workspace.yaml
```
packages:
  - packages/*
```
npm/yarn/bunの場合は、代わりにルートのpackage.jsonにworkspacesフィールドを追加します：
package.json
```
{
  "workspaces": ["packages/*"]
}
```
nx initを実行し（まだの場合）、その後プラグインを追加します。

プラグインの追加

nx addを使用します。これにより、Nxインストールと互換性のあるバージョンでプラグインがインストールされ、その後initジェネレーターが実行されてワークスペースが設定されます。

pnpm nx add @aws/nx-plugin

yarn nx add @aws/nx-plugin

npx nx add @aws/nx-plugin

bunx nx add @aws/nx-plugin

完了すると、ワークスペースの準備が整います — 必要なジェネレーターを選択して、プロジェクトの生成を開始してください。

このジェネレーターが設定する内容

プラグインを追加すると、ワークスペースがプラグインのジェネレーターを実行するために必要な決定論的な変更が行われます。ワークスペースのモジュール形式を保持します。ルートのpackage.jsonにtype: "module"があるワークスペースはESMのままで、それ以外はCommonJSのままであり、生成されたコードもそれに従います。既存のファイルを上書きすることはなく、既存の設定によっては、このステップの後に手動で変更を加える必要がある場合があります。

以下のファイルを作成または更新します。

aws-nx-plugin.config.mts 選択したIaCプロバイダー（CDKまたはTerraform）とコンテナエンジンを記録します。ジェネレーターはここからiac.providerを読み取ります
nx.json compileターゲットに同期ジェネレーター（@nx/js:typescript-syncと@aws/nx-plugin:ts#sync）を登録し、TypeScriptプロジェクト参照が同期されるようにします
tsconfig.json ワークスペースのプロジェクトを参照するルートTypeScript設定。NxのTypeScript同期が最新の状態に保ちます
tsconfig.base.json プラグインのTypeScriptプロジェクトが拡張する共有コンパイラオプション（以下で何を持つかを参照）
pnpm-workspace.yaml（pnpmのみ）プラグインの依存関係が必要とするビルドスクリプト（ @swc/core、esbuild、nx、sharp）を許可リストに追加します
package.json 一般的なタスクのための便利なスクリプト、およびnx、@nx/js、@nx/workspace、typescript、Biomeの開発依存関係
biome.json デフォルトのBiomeフォーマッターとリンター設定
.mcp.json 無効にされていない限り、サポートされているコーディングエージェント用のMCPサーバーを設定します（.cursor/、.kiro/、.gemini/、.vscode/、.codex/の同等物も含む）

MCPサーバーの設定は--mcp=falseで無効にできます。

作成されたtsconfig.base.jsonが持つコンパイラオプションを確認するにはここをクリックしてください。

オプション

パラメータ	型	デフォルト	説明
iac	cdk \| terraform	cdk	優先するIaCプロバイダー。
mcp	boolean	true	コーディングエージェントが使用するAWS MCP serverのNx Pluginを設定するかどうか。
containers	infer \| docker \| finch	infer	ビルド/プッシュ/ログインに使用するコンテナエンジン。'infer'はdockerがインストールされている場合はdockerを選択し、それ以外の場合はfinchを選択します(どちらもインストールされていない場合はdockerにフォールバックします)。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します(後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます)。最後に一度だけインストールします。

トラブルシューティング

`The workspace is out of sync`

TypeScriptプロジェクト参照の同期が必要です。initは同期ジェネレーターを登録します。実行してください。

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

インストール中の`ERR_PNPM_IGNORED_BUILDS`

pnpmは許可リストに載っていないパッケージのインストールスクリプトをスキップします。initはプラグインのツールが必要とするもの（@swc/core、esbuild、nx、sharp）をpnpm-workspace.yamlで許可リストに追加しますが、nx add @aws/nx-plugin自体の実行中 — initが実行される前 — にブロックが発生する可能性があります。pnpm approve-buildsを実行してリストされたパッケージを承認する（またはallowBuilds:の下に追加する）してから、インストールを再実行してください。

`nx sync`がハングする、または`plugin worker ... exited before the connection was established`

同じnode_modulesツリーに2つの異なるnxバージョンが存在する場合（npm ls nxを実行して確認）、それらのプラグインワーカーIPCがデッドロックします。initジェネレーターは、プラグイン自身の@nx/*パッケージが解決するバージョンにルートのnx devDependencyを固定しますが、異なるパッチバージョンで別の@nx/*パッケージを後でインストールすると、不一致が再導入される可能性があります。ルートのpackage.jsonのすべてのnxと@nx/*エントリを単一バージョンに揃えて、再インストールしてください。

`Recursive task invocation detected`

ルートのpackage.jsonがNxプロジェクトとして登録されており（"nx"キーがあり、nx initがシングルパッケージレポ用に追加します）、かつnx run-many --target buildのbuildスクリプトを持っています。Nxはルートに自分自身を呼び出すbuildターゲットを推論します。ソースをpackages/<your-package>/に移動して、ルートがプロジェクトではなくワークスペースマニフェストになるようにします — シングルパッケージプロジェクトを参照してください。（Nx自身のスタンドアロンプリセットは、ルートパッケージに"nx": { "includedScripts": [] }を設定することでこれを回避します。より迅速な代替として同じことができます。）

プラグインを追加した後の既存プロジェクトのTypeScriptエラー（`TS6059`、`TS7016`、`TS5011`、`NG4006`）

プラグイン自身が生成したプロジェクトは、プロジェクトごとのtsconfig.lib.jsonに必要なTypeScript設定を持っているため、tsconfig.base.jsonに関係なくビルドされます。これらのエラーは、代わりに、initが作成したtsconfig.base.json（composite/emitDeclarationOnly/nodenextを含む）を継承しているが、それらの設定と互換性がない既存のプロジェクトに表示されます — 例えば、AngularコンパイラはemitDeclarationOnlyを拒否し（NG4006）、rootDirなしでoutDirを設定するプロジェクトは今では必要です（TS5011）。それらのプロジェクトに対して、競合するオプションを再宣言するプロジェクトごとのtsconfigオーバーライドを追加する（例："rootDir": "src"）か、プラグインのプロジェクトと自分のプロジェクトを別々のベース設定に向けてください。

initは既存のtsconfig.base.jsonを決して書き換えません。それを継承するプロジェクトを静かに壊すことができないようにするためです — これらの不一致を解決することは、コードベースに対してあなただけができる決定です。