Skip to content
@aws/nx-plugin
Blog

CloudScapeウェブサイト

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

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

使用方法

CloudScapeウェブサイトの生成

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

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

    オプション

    パラメータ 型 デフォルト 説明
    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ターゲットを使用してデプロイ済みアプリケーションから設定ファイルを取得できます：

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

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

    ローカル開発サーバー

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

    Serveターゲット

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

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

    Terminal window
    pnpm nx run <my-website>:serve

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

    Serve Localターゲット

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

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

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

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

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

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

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

    ビルド

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

    Terminal window
    pnpm nx run <my-website>:build

    テスト

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

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

    テストの実行コマンド：

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