クイックスタートガイド

このガイドでは、@aws/nx-pluginのインストールと基本的な使用方法について説明し、AWS上でのプロジェクト構築を迅速化する方法を解説します。

Tip

より詳細なフルスタックアプリケーション構築チュートリアルについては、ダンジョンアドベンチャーチュートリアルをご覧ください。

前提条件

作業を進める前に以下のグローバル依存関係が必要です：

必須要件

• Git
• Node >= 22（バージョン管理にはNVMの使用を推奨）
  • 確認コマンド: node --version
• PNPM >= 10（代替としてYarn >= 4、Bun >= 1、NPM >= 10も使用可能）
  • 確認コマンド: pnpm --version、yarn --version、bun --version または npm --version
• UV >= 0.5.29
  1. Python 3.12のインストール: uv python install 3.12.0
  2. 確認コマンド: uv python list --only-installed
• ターゲットAWSアカウントに設定されたAWS認証情報（アプリケーションのデプロイ先）

推奨要件

• 一部のジェネレータで必要なDocker
• CDKの代わりにTerraformをIaCとして使用する場合に必要なTerraform >= 1.12
  • 確認コマンド: terraform --version
• VSCodeユーザー向けNx Console VSCodeプラグインのインストール推奨

Tip

Amazon Q Developer、Cursor、Claude Code、ClineなどのAIアシスタントを使用する場合は、Nx Plugin for AWS MCP serverのインストールも推奨します。

ステップ1: 新しいNxワークスペースの初期化

以下のコマンドを実行して、任意のパッケージマネージャーでNxワークスペースを作成します：

pnpm

npx create-nx-workspace@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --ci=skip

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --ci=skip

Tip

IaC（Infrastructure as Code）プロバイダーとしてCDKまたはTerraformを選択するプロンプトが表示されます。--iacProviderオプションを付けて実行することでプロンプトをスキップできます：

CDK

pnpm

npx create-nx-workspace@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip

Terraform

pnpm

npx create-nx-workspace@21.4.1 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

yarn

npx create-nx-workspace@21.4.1 my-project --pm=yarn  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

npm

npx create-nx-workspace@21.4.1 my-project --pm=npm  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

bun

npx create-nx-workspace@21.4.1 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip

完了したら、プロジェクトディレクトリに移動します：

cd my-project

ステップ2: ジェネレータを使用したプロジェクトのスキャフォールディング

このクイックスタートガイドでは、tRPC API、Reactウェブサイト、Cognito認証、CDK/Terraformインフラストラクチャを追加します。プロジェクトタイプに応じて、任意のジェネレータの組み合わせで迅速にプロジェクトを構築できます。左のナビゲーションバーにある__ガイド__から全オプションリストをご確認ください。

tRPC APIの追加

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

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

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

これによりpackages/demo-apiフォルダ内にAPIが作成されます。

Reactウェブサイトの追加

VSCode

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

CLI

pnpm

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

yarn

yarn nx g @aws/nx-plugin:ts#react-website --name=demo-website

npm

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

bun

bunx nx g @aws/nx-plugin:ts#react-website --name=demo-website

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

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

npm

npx nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

bun

bunx nx g @aws/nx-plugin:ts#react-website --name=demo-website --dry-run

packages/demo-websiteに新しいReactウェブサイトがスキャフォールドされます。

Cognito認証の追加

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

yarn

yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

npm

npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

bun

bunx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo

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

pnpm

pnpm nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

npm

npx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

bun

bunx nx g @aws/nx-plugin:ts#react-website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --dry-run

ウェブサイトにCognito認証を追加するためのインフラストラクチャとReactコードを設定します。

フロントエンドとバックエンドの接続

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

yarn

yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

npm

npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

bun

bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api

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

pnpm

pnpm nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

yarn

yarn nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

npm

npx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

bun

bunx nx g @aws/nx-plugin:api-connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --dry-run

ウェブサイトがtRPC APIを呼び出せるように必要なプロバイダーを設定します。

インフラストラクチャの追加

選択したIaCプロバイダーに基づいてインフラストラクチャプロジェクトを追加します。

CDK

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra

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

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --dry-run

AWSにインフラストラクチャをデプロイするためのCDKアプリを設定します。

Terraform

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra

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

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --dry-run

AWSにインフラストラクチャをデプロイするためのTerraformプロジェクトを設定します。

ステップ3: ローカル環境でのウェブサイトとAPIの実行

以下のコマンドでウェブサイトと接続されたAPIのローカル開発サーバーを起動します：

pnpm

pnpm nx run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

ウェブサイトはhttp://localhost:4200で利用可能になります。

ウェブサイトとAPIへの変更は、両方のローカルサーバーがホットリロードされるためリアルタイムで反映されます。

ステップ4: クラウドリソースの定義とAWSへのデプロイ

CDK

packages/infra/src/stacks/application-stack.tsを開き、以下のコードを追加します：

import * as cdk from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from ':my-project/common-constructs';
import { Construct } from 'constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'identity');
    const api = new DemoApi(this, 'api', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

これがフルスタックアプリケーションをデプロイするために必要なCDKコードの全量です。

Terraform

packages/infra/src/main.tfを開き、以下のコードを追加します：

# @aws/nx-pluginの使用状況追跡モジュール
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

# ユーザーアイデンティティのデプロイ
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# APIのデプロイ
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"
}

# 認証ユーザーへのAPI呼び出し権限付与
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "認証ユーザーがAPIを呼び出すためのポリシー"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Action = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

# ウェブサイトのデプロイ
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

これがフルスタックアプリケーションをデプロイするために必要なTerraformコードの全量です。

インフラストラクチャのビルドとデプロイ

以下のコマンドでプロジェクトをビルドします：

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Tip

リンターエラーが発生した場合は、以下のコマンドで自動修正できます：

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

インフラストラクチャのブートストラップを実行します：

CDK

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Tip

CDKブートストラップは、ターゲットデプロイAWSリージョンと、ウェブサイト用AWS WAF WebACLのデプロイに必要なus-east-1の両方で実行する必要があります。

Terraform

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Tip

TerraformブートストラップはTerraform状態ファイルを保存するS3バケットを作成します。これはAWSアカウント/リージョン組み合わせごとに1回のみ実行すれば十分です。

プロジェクトをデプロイします：

CDK

pnpm

pnpm nx run infra:deploy my-project-sandbox/*

yarn

yarn nx run infra:deploy my-project-sandbox/*

npm

npx nx run infra:deploy my-project-sandbox/*

bun

bunx nx run infra:deploy my-project-sandbox/*

Terraform

pnpm

pnpm nx run infra:apply

yarn

yarn nx run infra:apply

npm

npx nx run infra:apply

bun

bunx nx run infra:apply

Tip

このコマンドは最初にterraform planを実行して変更内容を表示し、その後変更を適用してインフラストラクチャをデプロイします。

ステップ5: デプロイ済みクラウドリソースでのウェブサイトテスト

1. runtime-config.jsonファイルの取得：

   pnpm

   pnpm nx run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

2. ローカルウェブサイトサーバーの起動

   pnpm

   pnpm nx run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

ウェブサイトはhttp://localhost:4200で利用可能になり、デプロイしたAPIと認証リソースを指すようになります。

---

おめでとうございます！🎉 @aws/nx-pluginを使用したフルスタックアプリケーションの構築とデプロイに成功しました！