(新登場)Nx Plugin for AWSでフルスタックAWSアプリのひな型を作ってみた

はじめに

AWS Labsが公開しているNx Plugin for AWSというツールがあります。React/tRPC/FastAPI/Strands Agents/CDK/Terraformといった構成のフルスタックAWSアプリを、Nxのジェネレーターでひな型化してくれるというものです。

公式サイトには「数日ではなく数分で構築」とあり、AIコーディングエージェント向けのMCPサーバーも標準で付いてくるとのことでした。

説明だけ読んでもツールの実力は分からないので、実際にワークスペースを作り、ジェネレーターを何本か動かし、ビルドが通るところまで確認しました。
この記事では、その過程で分かったことと、ドキュメントを読んで把握した仕様をあわせてまとめます。

Nx Plugin for AWSとは

Nx Plugin for AWSは、Nx(モノレポ管理ツール)の上に構築されたジェネレーター集です。
API、ウェブサイト、AIエージェント、データベース、CDK/Terraformインフラといったコンポーネントを、それぞれ単体で追加したり、後から接続したりできます。

ドキュメントを読んで押さえておくとよいと感じたポイントが2つあります。

1つは、生成されるコードが素のフレームワークコードだという点です。
React、tRPC、FastAPI、CDK、Terraformといった既存のフレームワークをそのまま使い、Nx Plugin for AWS独自のラッパーAPIやランタイム依存を挟みません。
ジェネレーターを実行した後は、生成物を普通のコードとして自由に書き換えられます。

もう1つは、アップグレードの仕組みです。
プラグイン側の生成パターンが改善されると、nx migrateでその差分を既存のコードに適用できます。
ただし、生成後に大きく手を入れた部分はパターンマッチングから外れるため、その場合は自動適用されず手動対応が必要になる、とドキュメントに明記されていました。

実際にワークスペースを作ってみる

まずはワークスペースを作成します。

npx pnpm@latest create @aws/nx-workspace nx-demo --pm=pnpm --interactive=false --nxCloud=skip --skipGit

18秒ほどでワークスペースが生成されました。
中身を見ると、Claude Code、Cursor、Kiro、Codex、Gemini向けのMCP設定ファイルが最初から揃っています。

.claude/settings.json
.codex/config.toml
.cursor/mcp.json
.gemini/settings.json
.kiro/settings
.mcp.json

.mcp.jsonの中身はこうなっていました。

{
  "mcpServers": {
    "nx-plugin-for-aws": {
      "command": "npx",
      "args": ["-y", "@aws/nx-plugin-mcp"]
    }
  }
}

このMCPサーバーが、Claude CodeなどのAIエージェントに「どのジェネレーターがあるか」「どう呼び出すか」を教える役割を持っています。
ドキュメントにあった「ワークスペースを作ってAIエージェントに頼むだけ」という説明は、この設定を指していると分かりました。

ジェネレーターでAPIとフロントエンドをつないでみる

CLIから直接ジェネレーターを呼んでも、中身は同じです。
まずtRPC APIを追加しました。

npx pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --no-interactive

packages/demo-apiにtRPCのハンドラーやミドルウェアが生成されるのは想定通りでしたが、それとは別にpackages/common/constructsというディレクトリも作られていました。
中を見るとAPI Gateway用のCDKコンストラクトが入っており、API用のインフラコードがAPI本体と同時に用意される仕組みになっているようです。

続けてReactのウェブサイトを追加します。

npx pnpm nx g @aws/nx-plugin:ts#react-website --name=demo-website --no-interactive

こちらもpackages/common/shadcnにshadcn/uiのコンポーネント一式、packages/common/constructsにCloudFront/S3のコンストラクトが追加されました。

最後に、ウェブサイトとAPIをconnectionジェネレーターでつなぎます。

npx pnpm nx g @aws/nx-plugin:connection --sourceProject=demo-website --targetProject=demo-api --auth=IAM --no-interactive

ここで生成されたuseDemoApi.tsxが次の内容でした。

import { useContext } from 'react';
import {
  DemoApiTRPCContext,
  type DemoApiTRPCContextValue,
} from '../components/DemoApiClientProvider';

export const useDemoApi = (): DemoApiTRPCContextValue['optionsProxy'] => {
  const container = useContext(DemoApiTRPCContext);
  if (!container) {
    throw new Error('useDemoApi must be used within DemoApiClientProvider');
  }
  return container.optionsProxy;
};

さらに興味深かったのはmain.tsxです。
手を加えていないのに、DemoApiClientProviderやQueryClientProviderでアプリ全体をラップする形に書き換わっていました。

root &&
  createRoot(root).render(
    <React.StrictMode>
      <RuntimeConfigProvider>
        <QueryClientProvider>
          <DemoApiClientProvider>
            <App />
          </DemoApiClientProvider>
        </QueryClientProvider>
      </RuntimeConfigProvider>
    </React.StrictMode>,
  );

ドキュメントに書かれていた「AST変換で既存ファイルを更新する」というのは、このことだったと分かりました。
新しいコンポーネントを作るだけでなく、既存のmain.tsxを解析してimportとラップ構造を書き換える、という部分まで自動化されています。

ビルドしてみて分かったこと

ここまで生成したプロジェクトをビルドしてみます。

npx pnpm nx run-many --target=build --exclude=common-constructs

最初はこのエラーで止まりました。

NX   The workspace is out of sync

[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.

ジェネレーターを続けて実行したことで、tsconfigのプロジェクト参照がずれたようです。
案内の通りnx syncを実行してから再度ビルドすると、今度は通りました。

✔  nx run @nx-demo/demo-api:test
✔  nx run @nx-demo/demo-api:lint
✔  nx run @nx-demo/demo-api:compile
✔  nx run @nx-demo/demo-api:bundle
✔  nx run @nx-demo/demo-website:test
✔  nx run @nx-demo/demo-website:compile
✔  nx run @nx-demo/demo-website:bundle

 NX   Successfully ran target build for 3 projects and 14 tasks they depend on

フォーマット、lint、テスト、コンパイル、バンドルまで一通り自動で流れ、ここまでは何もコードを書かずに通りました。
ただし、複数のジェネレーターを続けて実行した直後はnx syncを挟む必要がある、という点は事前に知っておいたほうがよさそうです。

何を生成できるか

ここからはドキュメントで確認した範囲になります。
ジェネレーターは大きく6つのカテゴリに分かれています。

• エージェンティック:Strands Agents(TypeScript/Python)、MCPサーバー、AgentCore Gateway/Harness
• API:tRPCまたはSmithy(TypeScript)、FastAPI(Python)
• イベント:型安全なLambda関数(TypeScript/Python)
• データベース:DynamoDB、Aurora(TypeScript/Python両対応)
• フロントエンド:React(Vite)ウェブサイト、Cognito認証、ドキュメントサイト(Astro)
• インフラ:AWS CDKまたはTerraform

connectionジェネレーターは今回試したウェブサイト↔API以外にも、ts#rdb#trpc-connectionやts#dynamodb#agent-connectionのように、データベースとAPI、データベースとエージェントといった組み合わせ用に個別のジェネレーターが用意されていました。

できないことと気になる制約

触ってみて、あるいはドキュメントを読んで分かった制約は次の通りです。

対応言語はTypeScriptとPythonの2つだけです。
既存プロジェクトへの追加ガイドには、GoやJavaといった他言語のプロジェクトもNx配下に置けるとありますが、それは「Nxのタスクランナーとして扱える」という意味にとどまり、Nx Plugin for AWS自体のジェネレーターがGoやJavaのコードを生成してくれるわけではありませんでした。

インフラはCDKかTerraformの2択で、フロントエンドはReact(Vite)一択です。
Next.jsやVue、Pulumiといった別の技術を使いたい場合は対象外になります。

単一パッケージのプロジェクトにあとから導入する場合、ドキュメントには「事前にソースコードをpackages/配下に移動し、ワークスペースマニフェストを整えてから導入する」という手順が書かれていました。
既存プロジェクトの構成によっては、導入前に一手間かかりそうです。

agentcore-harnessジェネレーターは、READMEの一覧で「experimental」と明記されていました。
エージェント関連の中でもここはまだ安定版という扱いではないようです。

そして今回実際に確認した通り、複数のジェネレーターを続けて実行するとnx syncが必要になる場面があります。
致命的な問題ではありませんが、「ジェネレーターを呼べば常に一発で通る」というわけではありませんでした。

導入するメリット

実際に触った上で感じたメリットは次の通りです。

• ウェブサイト、API、データベース、インフラをそれぞれ単体のコマンドで追加でき、connectionジェネレーターが型安全なクライアントとProviderのラップまで自動でやってくれる
• 生成されるのはReact、tRPC、FastAPI、CDK、Terraformといった既存フレームワークのコードそのもので、Nx Plugin for AWS独自の書き方を新しく覚える必要がない
• MCPサーバーが最初から設定されているため、Claude CodeなどのAIエージェントに「APIとウェブサイトをつないで」と頼むだけでジェネレーターを呼んでもらえる

導入のデメリットと注意点

一方で、気になった点もあります。

• Nxという別のビルドシステムに依存するため、Nxのキャッシュや依存関係グラフの考え方を新しく覚える必要がある
• 生成後にコードを大きく書き換えると、nx migrateによるパターンマッチングの対象から外れ、以降のアップグレードが自動適用されなくなる
• v1.0.0でリリースはされているものの、AWS公式のサポート対象サービスではなくAWS Labsのオープンソースプロジェクトという位置づけで、agentcore-harnessのように一部の機能はまだexperimentalの段階にある

どんなときに使うと効果があるか

今回の範囲で見た限り、Nx Plugin for AWSが効果を発揮しそうなのは、React+tRPC(またはFastAPI)+CDK(またはTerraform)という構成でAWSのフルスタックアプリを一から作る場面です。
ウェブサイト、API、エージェント、データベースをまたいで手作業で配線する部分をconnectionジェネレーターが肩代わりしてくれるため、プロトタイプやハッカソン用のアプリを短時間で立ち上げたい場合には向いていると感じました。

逆に、Next.jsやVueなど別のフロントエンド、CDK/Terraform以外のIaCをすでに採用しているチームにとっては、対象外の技術を書き換えてまで導入するメリットは薄いと思います。

実際に手を動かしてみると、ドキュメントに書かれている「型安全なクライアントの自動生成」や「既存ファイルのAST変換」は誇張ではなく、その通りに動きました。
一方でnx syncのような細かい手間も実際にあったので、導入する場合は一度小さなワークスペースで試してから判断するのがよさそうです。

最後まで読んでいただきありがとうございました。