クイックスタートガイド

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

フルスタックチュートリアル

フルスタックアプリケーションを構築するためのより詳細なチュートリアルについては、Dungeon Adventure チュートリアルをご覧ください。

前提条件

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

必須

• 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 のインストールをお勧めします。

AIアシスタントのセットアップ

Kiro、Kiro CLI、Cursor、Claude Code、Clineなどのアシスタントを使用している場合は、Nx Plugin for AWS MCPサーバーをインストールすることもお勧めします。

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

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

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

IaC プロバイダーの選択

優先する Infrastructure as Code (IaC) プロバイダーとして、CDK または Terraform のいずれかを選択するよう求められます。--iac を指定してコマンドを実行することで、プロンプトをスキップできます：

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

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

cd my-project

ステップ 2: ジェネレーターを使用してプロジェクトをスキャフォールドする

このクイックスタートガイドでは、tRPC API、React ウェブサイト、Cognito 認証、および CDK または Terraform インフラストラクチャを追加します。構築するプロジェクトのタイプに応じて、ジェネレーターの任意の組み合わせを選択して、プロジェクトを迅速にブートストラップできます。オプションの完全なリストについては、左側のナビゲーションバーの Generators を確認するか、グラフビルダーを試して、ワークスペースを視覚的に構築してください。

ショートカットとして、以下のボタンを使用して、完全なアプリケーションをスキャフォールドするコマンドをコピーできます。

Loading the diagram…

AI で構築

Nx Plugin for AWS MCP Server はワークスペースにすでに設定されているため、CLI コマンドを自分で入力する代わりに、Kiro や Claude などのお気に入りの AI コーディングエージェントにこれらのプロジェクトを構築するよう依頼できます。

それ以外の場合は、以下の手順に従って各ジェネレーターを自分で実行してください。

tRPC API を追加する

CLI

pnpm

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

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

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

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

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

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

VSCode

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

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

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

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

Cognito 認証を追加する

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

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

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

VSCode

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

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

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

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

CDK

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

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

Terraform

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

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

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

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

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

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

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

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

CDK

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

import { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
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 を開き、以下のコードを追加します：

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

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

これが、フルスタックアプリケーションをデプロイするために記述する必要のあるすべての 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

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

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 の両方で必要です。

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 と認証用にデプロイしたリソースを指します。

---

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