クイックスタートガイド

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

前提条件

続行する前に、以下のグローバル依存関係が必要です：

必須

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

推奨

• PNPM >= 11（お好みで Yarn >= 4、Bun >= 1、または NPM >= 11 も使用できます）
  • 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 のインストールをお勧めします。

ステップ 1: ワークスペースを作成する

お好みのパッケージマネージャーで Nx ワークスペースを作成し、作成されたディレクトリを開きます：

ワークスペースを作成@aws/nx-workspace

pnpm

$ pnpm create @aws/nx-workspace my-project

yarn

$ yarn create @aws/nx-workspace my-project

npm

$ npm create @aws/nx-workspace -- my-project

bun

$ bun create @aws/nx-workspace my-project

コマンドを組み立てる3

workspace必須

iac

cdkterraform

containers

inferdockerfinch

cd my-project

Infrastructure as Code プロバイダーとして CDK または Terraform のいずれかを選択するよう求められます。

ステップ 2: アプリケーションを構築する

フルスタックアプリケーションを構築します：tRPC API、React ウェブサイト、Cognito 認証、および CDK または Terraform インフラストラクチャです。AI アシスタントにスキャフォールドを依頼するか、ジェネレーターを自分で実行してください。どちらのルートでも同じワークスペースに到達します。

AI を使用する

1. AI コーディングアシスタントでワークスペースを開きます。

   新しいワークスペースには、プラグインの MCP サーバーが Kiro、Claude Code、Cursor、Gemini CLI、GitHub Copilot、OpenAI Codex 用にすでに設定されているため、アシスタントはセットアップなしでプラグインのジェネレーターを検索して実行できます。

2. アプリケーションを依頼します：

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   アシスタントは MCP サーバーを通じてジェネレーターを発見し、依存関係が必要とする順序で実行します。変更内容を確認してから、ステップ 3 に進んでください。

CLI を使用する

アプリケーションをスキャフォールドするジェネレーターを実行します。以下のボタンを使用してすべてをコピーするか、図の下に説明されているように各ジェネレーターを自分で実行してください。

CDK

Loading the diagram…

Terraform

Loading the diagram…

構築するプロジェクトのタイプに応じて、ジェネレーターの任意の組み合わせを選択して、プロジェクトを迅速にブートストラップできます。オプションの完全なリストについては、左側のナビゲーションバーの Generators を確認するか、グラフビルダーを試して、ワークスペースを視覚的に構築してください。

tRPC API を追加する

このジェネレーターを実行@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

VSCode

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

このステップのオプション2

name必須

framework

trpc

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

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

React ウェブサイトを追加する

このジェネレーターを実行@aws/nx-plugin:ts#website

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website --no-interactive

VSCode

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

このステップのオプション1

name必須

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

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

Cognito 認証を追加する

このジェネレーターを実行@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

VSCode

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

このステップのオプション1

project必須

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

これにより、ウェブサイトに Cognito 認証を追加するために必要なインフラストラクチャと React コードが設定されます。

フロントエンドとバックエンドを接続する

このジェネレーターを実行@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

VSCode

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

このステップのオプション2

sourceProject必須

targetProject必須

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

これにより、ウェブサイトが tRPC API を呼び出せるようにするために必要なプロバイダーが設定されます。

インフラストラクチャを追加する

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

CDK

このジェネレーターを実行@aws/nx-plugin:ts#infra

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#infra --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#infra --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#infra --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#infra --no-interactive

VSCode

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

このステップのオプション1

name必須

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

これにより、AWS にインフラストラクチャをデプロイするために使用できる CDK アプリが設定されます。

Terraform

このジェネレーターを実行@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

VSCode

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

このステップのオプション1

name必須

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

これにより、AWS にインフラストラクチャをデプロイするために使用できる Terraform プロジェクトが設定されます。

ステップ 3: ウェブサイトと API をローカルで実行する

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

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

ウェブサイトは http://localhost:4200 で利用できます。

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

試してみる: ウェブサイトから API を呼び出す

ステップ 4: クラウドリソースを定義して AWS にデプロイする

CDK

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

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: 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 を開き、以下のコードを追加します：

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the 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
}

# Deploy website
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]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

これが、フルスタックアプリケーションをデプロイするために記述する必要のあるすべての Terraform です。

インフラストラクチャをビルドしてデプロイする

次に、以下のコマンドを実行してプロジェクトをビルドします：

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Lint とフォーマットエラーの修正

Lint またはフォーマットエラーが発生した場合は、以下のコマンドを実行して自動的に修正できます。

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

ワークスペースが同期されていません

ビルドで The workspace is out of sync と報告された場合は、プロンプトを受け入れてワークスペースを同期するか、ビルドを再試行する前に以下の同期コマンドを直接実行してください：

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

これにより、インポートに必要な TypeScript プロジェクト参照と package.json 依存関係エントリが書き込まれます。

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

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

ブートストラップリージョン

CDK ブートストラップは、ターゲットデプロイメント AWS リージョンと、ウェブサイトの AWS WAF WebACL のデプロイを可能にするための us-east-1 の両方で必要です。他の場所にデプロイする場合は、us-east-1 もブートストラップしてください：

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

一度だけのセットアップ

Terraform ブートストラップは、Terraform ステートファイルを保存するための S3 バケットを作成します。これは、AWS アカウント/リージョンの組み合わせごとに一度だけ実行する必要があります。

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

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

Apply の前に Plan

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

ステップ 5: デプロイされたクラウドリソースでウェブサイトをテストする

1. runtime-config.json ファイルを取得します：

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. ローカルウェブサイトサーバーを起動します

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

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

サインインするには、Cognito ユーザープールでユーザーを作成する必要があります。

AWS CLI を使用した手順についてはここをクリックしてください

ウェブサイトは CloudFront からも提供されます。デプロイ後にターミナルに表示されるディストリビューションドメイン名を開いて、完全に AWS 上で実行されているバージョンを使用してください。

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

ステップ 6: クリーンアップ

完了したら、継続的なコストを避けるためにデプロイしたリソースを削除します：

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

保持されるリソース

Cognito ユーザープールは削除保護が有効になった状態で作成されるため、自動的には削除されません。不要になったら、ユーザープールと Cognito が SMS メッセージの送信に使用する IAM ロールを手動で削除してください。

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

保持されるリソース

Cognito ユーザープールは削除保護が有効になった状態で作成されるため、自動的には削除されません（destroy コマンドは失敗を報告します）。不要になったら、ユーザープールと Cognito が SMS メッセージの送信に使用する IAM ロールを手動で削除してください。

ブートストラップリソースを削除するには、以下に従ってください：

CDK

us-east-1 を含む、ブートストラップしたすべてのリージョンでブートストラップスタックを削除します。これにより、ブートストラップロールとコンテナイメージリポジトリが削除されます：

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

アセットバケット

アセットバケットは意図的に保持されるため、別途削除してください。

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

Terraform ステートも削除されます

これにより、Terraform ステートを保持している S3 バケットが空にされて削除されるため、デプロイされたすべてのインフラストラクチャを削除した後にのみ実行してください。

---

次のステップ

• Dungeon Adventure チュートリアル — このガイドよりも詳細なウォークスルーとして、フルスタック AI ダンジョンアドベンチャーゲームを構築します。
• ワークスペース — ワークスペースのレイアウトと、ジェネレーターが共有する設定について説明します。
• 既存のプロジェクトに追加する — 既存のコードベースでプラグインを採用します。