CloudScapeウェブサイト

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

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

Note

このジェネレータはCloudScapeを初期設定しますが、本質的にはReactプロジェクトジェネレータです。必要に応じて他のデザインシステムやコンポーネントライブラリに移行するようコードを変更可能です。

使用方法

CloudScapeウェブサイトの生成

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

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	The name of the application.
directory	string	packages	The directory of the new application.

ジェネレータの出力

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

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

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

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

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

    • Directorywelcome

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

またpackages/common/constructsディレクトリにウェブサイトデプロイ用のCDKインフラストラクチャコードを作成します：

• Directorysrc

  • Directoryapp

    • Directorystatic-websites

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

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

CloudScapeウェブサイトの実装

ReactドキュメントはReactの基本を学ぶのに適しています。CloudScapeドキュメントでは利用可能なコンポーネントとその使用方法を確認できます。

ルーティング

ルート/ページの作成

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ドキュメントを参照してください。

ランタイム設定

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

インフラストラクチャ

RuntimeConfig CDKコンストラクトを使用して設定の追加・取得が可能です。@aws/nx-pluginが生成するCDKコンストラクト（tRPC APIやFastAPIなど）は自動的に適切な値をRuntimeConfigに追加します。

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

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);

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

    // runtime-config.jsonへ自動デプロイ
    new MyWebsite(this, 'MyWebsite');
  }
}

runtime-config.jsonに設定が含まれるよう、ウェブサイトの宣言は他のコンストラクトより後に行う必要があります。

ウェブサイトコード

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

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

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

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

ローカルランタイム設定

ローカル開発サーバー実行時には、バックエンドURLや認証設定などを知るためpublicディレクトリに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"

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

ローカル開発サーバー

serveまたはserve-localターゲットでローカル開発サーバーを起動できます。

Serveターゲット

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

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

pnpm

pnpm nx run <my-website>:serve

yarn

yarn nx run <my-website>:serve

npm

npx nx run <my-website>:serve

bun

bunx nx run <my-website>:serve

このターゲットは「本番」APIを参照しながらウェブサイトを変更する場合に有用です。

Serve Localターゲット

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

このモードではruntime-config.jsonがローカルAPI URLを指すよう自動上書きされます。

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

pnpm

pnpm nx run <my-website>:serve-local

yarn

yarn nx run <my-website>:serve-local

npm

npx nx run <my-website>:serve-local

bun

bunx nx run <my-website>:serve-local

このターゲットはAPIとウェブサイトを同時に開発する際に便利です。

このモードでruntime-config.jsonが存在しない場合、CloudScape Website AuthジェネレータでCognito認証を設定していても、ログインがスキップされ認証ヘッダーが付加されません。

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

ビルド

buildターゲットでプロダクションビルドを実行します。Viteを使用してdist/packages/<my-website>/bundleディレクトリにバンドルを生成し、型チェック・コンパイル・リンタを実行します。

pnpm

pnpm nx run <my-website>:build

yarn

yarn nx run <my-website>:build

npm

npx nx run <my-website>:build

bun

bunx nx run <my-website>:build

テスト

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

React Testing Libraryがインストール済みで、テスト作成に使用できます。詳細はReact Testing Libraryドキュメントを参照してください。

テストの実行コマンド：

pnpm

pnpm nx run <my-website>:test

yarn

yarn nx run <my-website>:test

npm

npx nx run <my-website>:test

bun

bunx nx run <my-website>:test

ウェブサイトのデプロイ

デプロイにはTypeScript Infrastructureジェネレータを使用してCDKアプリケーションを作成することを推奨します。

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');
  }
}