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

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

前提条件

必須

Git
Node >= 22 (NVM のようなツールを使用してノードバージョンを管理することをお勧めします)
- node --version を実行して確認してください
UV >= 0.5.29
1. uv python install 3.14.0 を実行して Python 3.14 をインストールします
2. uv python list --only-installed で確認してください

推奨

PNPM >= 11（お好みで Yarn >= 4、Bun >= 1、または NPM >= 10 も使用できます）
- pnpm --version、yarn --version、bun --version、または npm --version を実行して確認してください
アプリケーションをデプロイするには（および一部のローカル開発ワークフローにも）、ターゲットの AWS アカウントに設定された AWS Credentials が必要です。
一部のジェネレーターには Docker または Finch >= 1.6.0 が必要です。Docker の場合、マルチプラットフォームビルドを設定する必要があります。Finch はマルチプラットフォームビルドを標準でサポートしています。
CDK の代わりに Infrastructure as Code としてこれを使用する場合は、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.1.1 init

yarn dlx nx@23.1.1 init

npx nx@23.1.1 init

bunx nx@23.1.1 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 一般的なタスクのための便利なスクリプト、および @aws/nx-plugin、@aws/nx-plugin-mcp、nx、@nx/js、@nx/workspace、typescript、Biome開発依存関係
biome.json デフォルトのBiomeフォーマッターとリンター構成
.mcp.json 無効にされていない限り、サポートされているコーディングエージェント用のMCPサーバーを構成します（.cursor/、.kiro/、.gemini/、.vscode/、.codex/ の同等物も含む）。ワークスペース自体の @aws/nx-plugin-mcp を実行するため、サーバーは常にワークスペースにインストールされているバージョンと一致します

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プロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます)。最後に一度だけインストールします。

トラブルシューティング

既存のTypeScriptライブラリで `nx build <project>` が機能しなくなった

最初の ts#project 実行時に、@nx/js/typescript プラグインがTypeScriptビルドターゲットを compile として推論するように構成されます（プラグインは lint、compile、test のオーケストレーションのために build を予約しています）。推論された build ターゲットに依存している既存のライブラリも compile として推論されます。nx run <project>:compile を実行するか、nx run-many --target build,compile を使用してください。project.json に明示的な build ターゲットを持つライブラリは影響を受けません。

`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/* エントリを単一のバージョンに揃えて再インストールしてください。

`ts.readConfigFile is not a function`

ワークスペースにTypeScript 7がインストールされていますが、Nxはまだサポートしていません。Nxのプラグインは、TypeScript 7が提供しなくなったTypeScriptのインプロセスコンパイラAPIに依存しています。ルート package.json の typescript をプラグインが使用するバージョンに固定し（init ジェネレーターは互換性のあるバージョンをインストールします）、再インストールしてください。

`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 を決して書き換えません。これは、それを継承するプロジェクトを静かに壊すことができないようにするためです。これらの不一致を解決することは、コードベースに対してあなただけが行える決定です。