Reactウェブサイト

このジェネレータはReactウェブサイトを新規作成し、デフォルトでshadcn/uiの設定と、静的ウェブサイトをクラウドにデプロイするためのAWS CDKまたはTerraformインフラストラクチャ（S3ホスティング、CloudFront配信、WAF保護）を構成します。

生成されるアプリケーションはビルドツールとバンドラーにViteを使用し、型安全なルーティングにTanStack Routerを採用しています。

UX Provider

デフォルトのuxProviderはshadcn/uiです。CloudscapeまたはNone（独自のコンポーネントライブラリを使用）も選択できます。

使用方法

Reactウェブサイトの生成

新しいReactウェブサイトは2つの方法で生成できます：

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

pnpm nx g @aws/nx-plugin:ts#website --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --dry-run

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	アプリケーションの名前。
framework	react	react	使用するフロントエンドフレームワーク。
directory	string	packages	新しいアプリケーションのディレクトリ。
subDirectory	string	-	プロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。
ux	none | cloudscape | shadcn	shadcn	優先するUXプロバイダー。
tailwind	boolean	true	ユーティリティファーストのスタイリングのためにTailwindCSSを有効にします。
tanstackRouter	boolean	true	型安全なルーティングのためにTanstackルーターを有効にします。
infra	cloudfront-s3 | none	cloudfront-s3	ウェブサイトをデプロイするインフラストラクチャのタイプ。
iac	inherit | cdk | terraform	inherit	優先するIaCプロバイダー。デフォルトでは、初期選択から継承されます。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレータの出力

ジェネレータは<directory>/<name>ディレクトリに以下のプロジェクト構造を作成します：

• index.html HTMLエントリポイント
• public 静的アセット
• Directorysrc

  • main.tsx Reactセットアップを含むアプリケーションエントリポイント
  • config.ts アプリケーション設定（ロゴなど）
  • Directorycomponents

    • AppLayout 全体のレイアウトとナビゲーションバー用コンポーネント
  • Directoryhooks

    • useAppLayout.tsx ネストされたコンポーネントからAppLayoutを調整するフック（Cloudscapeのみ）
  • Directoryroutes

    • index.tsx TanStack Router用のサンプルルート（ページ）
  • styles.css グローバルスタイル
• vite.config.mts ViteとVitestの設定
• tsconfig.json ソースとテスト用の基本TypeScript設定
• tsconfig.app.json ソースコード用TypeScript設定
• tsconfig.spec.json テスト用TypeScript設定

TanStack Routerなし

TanStack Routerを使用しない選択をした場合、routesディレクトリの代わりにアプリケーションエントリポイントとしてシンプルなsrc/app.tsxファイルが提供されます。

インフラストラクチャ

このジェネレータは選択した iacProvider に基づいてInfrastructure as Codeを生成するため、packages/common に関連するCDKコンストラクトまたはTerraformモジュールを含むプロジェクトを作成します。

共通のInfrastructure as Codeプロジェクトは以下の構造を持ちます：

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用コンストラクト

      • …
    • Directorycore/ app 内のコンストラクトで再利用される汎用コンストラクト

      • …
    • index.ts app からコンストラクトをエクスポートするエントリーポイント
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは ts#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用Terraformモジュール

      • …
    • Directorycore/ app 内のモジュールで再利用される汎用モジュール

      • …
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは terraform#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

ジェネレータは選択したiacProviderに基づいてウェブサイトをデプロイするためのインフラストラクチャコードを作成します：

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directorystatic-websites

      • <name>.ts ウェブサイト固有のインフラストラクチャ
  • Directorycore

    • static-website.ts 汎用StaticWebsiteコンストラクト

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorystatic-websites

      • Directory<name>

        • <name>.tf ウェブサイト固有のモジュール
  • Directorycore

    • Directorystatic-website

      • static-website.tf 汎用静的ウェブサイトモジュール

アーキテクチャ

デプロイされたウェブサイトは以下のアーキテクチャを持ちます：

セキュリティヘッダー

CloudFrontディストリビューションは、すべてのレスポンスにStrict-Transport-Security、X-Content-Type-Options、X-Frame-Options: DENY、Referrer-Policy、およびContent-Security-Policyを設定するレスポンスヘッダーポリシーを適用します。

デフォルトのContent-Security-Policyが適用されます。これはXSSやクリックジャッキングを軽減するためにスクリプトとフレーミングを制限しつつ、デプロイ時にのみURLが判明するAWSサービスエンドポイント（API Gateway、Cognito、Bedrock AgentCoreなど）をウェブサイトが呼び出せるようHTTPSおよびWSS接続を許可します。ポリシーを調整する場合（例えばconnect-srcを特定のオリジンに絞り込む場合）、生成されたstatic-website.ts（CDK）またはstatic-website.tf（Terraform）のcontent_security_policy値を編集してください。

runtime-config.jsonはCache-Control: no-cacheで配信されるため、ブラウザは再デプロイ後に古いキャッシュコピーではなく常に最新の設定を取得します。

Reactウェブサイトの実装

ReactドキュメントはReact開発の基本を学ぶのに適しています。

ux = cloudscape

Cloudscapeドキュメントでは利用可能なコンポーネントとその使用方法を確認できます。

ux = shadcn

shadcn/uiドキュメントでは利用可能なコンポーネントとその使用方法を確認できます。

ルート

ルート/ページの作成

ウェブサイトにはデフォルトでTanStack Routerが設定されています。新しいルートを簡単に追加できます：

1. ローカル開発サーバーを起動
2. src/routesに新しい<page-name>.tsxファイルを作成（ファイルツリー内の位置がパスを表す）
3. RouteとRouteComponentが自動生成されます。ここでページの構築を開始できます

ページ間のナビゲーション

ページ間の移動にはLinkコンポーネントまたはuseNavigateフックを使用します：

import { Link, useNavigate } from '@tanstack/react-router';

export const MyComponent = () => {
  const navigate = useNavigate();

  const submit = async () => {
    const id = await ...
    // 非同期処理後のリダイレクトに`navigate`を使用
    navigate({ to: '/products/$id', { params: { id }} });
  };

  return (
    <>
      <Link to="/products">キャンセル</Link>
      <Button onClick={submit}>送信</Button>
    </>
  )
};

詳細はTanStack Routerドキュメントを参照してください。

ランタイム設定

インフラストラクチャからの設定はランタイム設定を通じてウェブサイトに提供されます。これにより、デプロイ時まで不明なAPI URLなどの詳細情報にアクセス可能になります。

インフラストラクチャ

CDK

RuntimeConfig CDKコンストラクトを使用して設定の追加・取得が可能です。@aws/nx-pluginジェネレータ（ts#trpc-apiやpy#fast-apiなど）で生成されたCDKコンストラクトは自動的にRuntimeConfigに値を追加します。

ウェブサイトCDKコンストラクトはランタイム設定のconnection名前空間をruntime-config.jsonファイルとしてS3バケットのルートにデプロイします。

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite, MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // Webサイトは任意の場所で宣言可能 — ランタイム設定は遅延解決されます
    new MyWebsite(this, 'MyWebsite');

    // RuntimeConfigに自動的に値を追加
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

CDKウェブサイトコンストラクト

CDKでは、ウェブサイトコンストラクトはスタック内の任意の場所で宣言できます。ランタイム設定はsynth時に遅延解決されるため、宣言順序に関係なくすべての値が含まれます。

Terraform

Terraformではランタイム設定はruntime-configモジュールで管理されます。@aws/nx-pluginジェネレータ（ts#apiやpy#apiなど）で生成されたTerraformモジュールは自動的にランタイム設定に値を追加します。

ウェブサイトTerraformモジュールはランタイム設定のconnection名前空間をruntime-config.jsonファイルとしてS3バケットのルートにデプロイします。

packages/infra/src/main.tf

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# ランタイム設定に自動的に値を追加
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# runtime-config.jsonとして自動デプロイ
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # ランタイム設定追加のためAPIを先にデプロイ
  depends_on = [module.my_api]
}

モジュールの順序

runtime-config.jsonに設定が含まれるよう、ランタイム設定に追加するモジュールの後にウェブサイトモジュールを宣言し、適切なdepends_onを設定して順序を確保する必要があります。

ウェブサイトコード

ウェブサイトではuseRuntimeConfigフックを使用してランタイム設定値を取得できます：

import { useRuntimeConfig } from '../hooks/useRuntimeConfig';

const MyComponent = () => {
  const runtimeConfig = useRuntimeConfig();

  // ランタイム設定値にアクセス
  const apiUrl = runtimeConfig.apis.MyApi;
};

ランタイム設定

ランタイム設定がAWS AppConfigにどのように保存されているか、およびサーバーサイドのコンシューマー（Lambda関数、エージェント）がどのように取得できるかについては、ランタイム設定ガイドを参照してください。

ローカルランタイム設定

ローカル開発サーバーを実行する際、バックエンドURLや認証設定などを認識させるため、publicディレクトリにruntime-config.jsonファイルが必要です。

ウェブサイトプロジェクトにはデプロイ済みアプリケーションからruntime-config.jsonを取得するload:runtime-configターゲットが設定されています：

pnpm

pnpm nx run <my-website>:"load:runtime-config"

yarn

yarn nx run <my-website>:"load:runtime-config"

npm

npx nx run <my-website>:"load:runtime-config"

bun

bunx nx run <my-website>:"load:runtime-config"

カスタムステージ名

CDK

インフラストラクチャプロジェクトのsrc/main.tsでステージ名のプレフィックスを変更した場合、ウェブサイトのproject.jsonファイルのload:runtime-configターゲットを更新する必要があります。

また、このターゲットは単一ステージがAWS認証情報の環境にデプロイされていることを前提としています。同一アカウント/リージョンに複数ステージをデプロイする場合はコマンドを調整してください。

Terraform

Terraformプロジェクトでは、load:runtime-configターゲットは直近のローカルterraform applyで作成されたruntime-config.jsonをコピーします。

ローカル開発サーバー

ローカル開発の標準コマンドはdevです。これは1つのコマンドでウェブサイト（および接続したAPIのローカルサーバー）を起動します：

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

devは以下で説明するserve-localターゲットのエイリアスです。serveとserve-localは、アプリケーションのどの部分をローカルで実行し、どの部分をデプロイ済みのAWSインフラストラクチャに向けるかを制御する必要がある場合に引き続き利用できます。接続されたプロジェクト全体でのローカル開発の概要、および複数のコンポーネントを持つプロジェクトでdevがどのように動作するかについては、ローカル開発ガイドを参照してください。

Serveターゲット

serveターゲットはウェブサイトのローカル開発サーバーを起動します。このターゲットを使用するには、ウェブサイトが連携するインフラストラクチャのデプロイとローカルランタイム設定の読み込みが必要です。

次のコマンドで実行できます：

pnpm

pnpm nx serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

このターゲットは「本番」デプロイされたAPIと連携しながらウェブサイトを変更する場合に有用です。

Devターゲット

devターゲットはViteのMODEをlocal-devに設定したローカル開発サーバーを起動し、接続ジェネレータで接続したAPIのローカルサーバーも同時に起動します。

このターゲットでサーバーを起動すると、runtime-config.jsonがローカルAPIのURLを指すように自動的に上書きされます。

次のコマンドで実行できます：

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

このターゲットはウェブサイトとAPIを同時に開発する際の迅速な反復処理に適しています。

ワークスペースのdevスクリプト

ワークスペースのルートpackage.jsonには、devターゲットを持つすべてのプロジェクトに対してdevターゲットを実行するdevスクリプトが含まれています：

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

これにより、ウェブサイト（およびdevターゲットを持つその他のプロジェクト）のローカル開発サーバーが1つのコマンドで起動します。このウェブサイトのみを実行するには、独自のdevターゲット（例：nx dev <my-website>）を使用してください。

モック認証

このモードで実行しruntime-config.jsonが存在しない場合、ts#website#authジェネレータでCognito認証を設定していても、ログインがスキップされローカルサーバーへのリクエストに認証ヘッダーが含まれません。

serve-localで認証を有効化するには、インフラストラクチャをデプロイしランタイム設定を読み込んでください。

Serve-Localの動作

serve-localで実行する際、他のデプロイ済みAWSリソースを指すためにAPIが必要とする環境変数を指定できます。例：

pnpm

DYNAMODB_TABLE_NAME=xxxxx pnpm nx serve-local <my-website>

yarn

DYNAMODB_TABLE_NAME=xxxxx yarn nx serve-local <my-website>

npm

DYNAMODB_TABLE_NAME=xxxxx npx nx serve-local <my-website>

bun

DYNAMODB_TABLE_NAME=xxxxx bunx nx serve-local <my-website>

ローカルAPIサーバーはローカルに設定されたAWS認証情報で実行されることに注意してください。

ビルド

buildターゲットでウェブサイトをビルドできます。これはbundle、compile、test、lintターゲットを実行し、型チェック、バンドル、テスト、リンターを実行します。

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

bundleターゲットはViteを使用して本番用バンドルをルートのdist/packages/<my-website>/bundleディレクトリに生成します。これはウェブサイトインフラストラクチャで使用されるデプロイ可能なアーティファクトです。単独で実行することもできます：

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

テスト

テストの作成方法は標準的なTypeScriptプロジェクトと同様です。詳細はTypeScriptプロジェクトガイドを参照してください。

React固有のテストにはReact Testing Libraryが事前にインストールされています。使用方法はReact Testing Libraryドキュメントを参照してください。

テストはtestターゲットで実行できます：

pnpm

pnpm nx test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

ウェブサイトのデプロイ

Reactウェブサイトジェネレータは選択したiacProviderに基づいてCDKまたはTerraformのインフラストラクチャコードを作成します。これを使用してウェブサイトをデプロイできます。

CDK

ウェブサイトのデプロイには、CDKアプリケーション作成用のts#infraジェネレータの使用を推奨します。

packages/common/constructsに生成されたCDKコンストラクトを使用してウェブサイトをデプロイできます。

packages/infra/src/stacks/application-stack.ts

import { Stack } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new MyWebsite(this, 'MyWebsite');
  }
}

この設定では以下が構成されます：

1. 静的ウェブサイトファイルホスティング用S3バケット
2. グローバルコンテンツ配信用CloudFrontディストリビューション
3. セキュリティ保護用WAF Web ACL
4. 安全なS3アクセスのためのOrigin Access Control
5. ウェブサイトファイルとランタイム設定の自動デプロイ

Terraform

ウェブサイトのデプロイには、Terraformプロジェクト作成用のterraform#projectジェネレータの使用を推奨します。

packages/common/terraformに生成されたTerraformモジュールを使用してウェブサイトをデプロイできます。

packages/infra/src/main.tf

# ウェブサイトのデプロイ
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

この設定では以下が構成されます：

1. 静的ウェブサイトファイルホスティング用S3バケット
2. グローバルコンテンツ配信用CloudFrontディストリビューション
3. セキュリティ保護用WAF Web ACL（us-east-1にデプロイ）
4. 安全なS3アクセスのためのOrigin Access Control
5. ウェブサイトファイルとランタイム設定の自動デプロイ

WAFプロバイダーリージョン

CloudFrontとWAFリソースはus-east-1リージョンにデプロイする必要があるため、aws.us_east_1プロバイダが必須です。Terraform設定にこのプロバイダを含めてください：

packages/infra/src/providers.tf

provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
}

接続

connectionジェネレータを使用して、このプロジェクトをワークスペース内の他のプロジェクトと統合できます。このプロジェクトに関連する接続は以下の通りです：

React to tRPCReactウェブサイトからtRPC APIを呼び出す

React to FastAPIReactウェブサイトからPython FastAPIを呼び出す

React to Smithy APIReactウェブサイトからSmithy APIを呼び出す

React to Python AgentReactウェブサイトからPython Agentを呼び出す

React to TypeScript AgentReactウェブサイトからTypeScript Agentを呼び出す

React to AG-UI AgentCopilotKit経由でAG-UIプロトコルを公開するAgentをReactウェブサイトから呼び出す

id>