React 网站

该生成器会创建一个配置了 CloudScape 的 React 网站，并生成 AWS CDK 或 Terraform 基础设施代码，用于将您的网站作为静态站点部署到云端，托管在 S3 中，通过 CloudFront 分发，并通过 WAF 提供保护。

生成的应用程序使用 Vite 作为构建工具和打包器，并采用 TanStack Router 实现类型安全的路由。

注意

虽然此生成器默认配置了 CloudScape，但它本质上是一个 React 项目生成器，您可以根据需要修改代码以迁移到其他设计系统或组件库。

使用方式

生成 React 网站

您可以通过两种方式生成新的 React 网站：

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#react-website
5. 填写必需参数
6. 点击 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

您还可以执行试运行以查看哪些文件会被更改

pnpm

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

yarn

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

npm

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

bun

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

选项配置

参数	类型	默认值	描述
name 必需	string	-	The name of the application.
directory	string	packages	The directory of the new application.
enableTailwind	boolean	true	Enable TailwindCSS for utility-first styling.
enableTanstackRouter	boolean	true	Enable Tanstack router for type-safe routing.
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

生成器输出

生成器将在 <directory>/<name> 目录下创建以下项目结构：

• index.html HTML 入口文件
• public 静态资源目录
• 文件夹src

  • main.tsx React 应用入口文件
  • config.ts 应用配置（如 logo）
  • 文件夹components

    • AppLayout 包含 CloudScape 整体布局和导航栏的组件
  • 文件夹hooks

    • useAppLayout.tsx 用于从嵌套组件调整 AppLayout 的钩子
  • 文件夹routes

    • 文件夹welcome

      • index.tsx 使用 @tanstack/react-router 的示例路由（页面）
  • styles.css 全局样式
• vite.config.ts Vite 和 Vitest 配置
• tsconfig.json 基础 TypeScript 配置（源码和测试）
• tsconfig.app.json 源码 TypeScript 配置
• tsconfig.spec.json 测试 TypeScript 配置

基础设施

由于该生成器会根据您选择的 iacProvider 以基础设施即代码的形式输出，它将在 packages/common 目录下创建一个包含相关 CDK 构造体或 Terraform 模块的项目。

通用的基础设施即代码项目结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ 针对特定项目/生成器的基础设施构造体

      • …
    • 文件夹core/ 被 app 目录构造体重用的通用构造体

      • …
    • index.ts 导出 app 目录构造体的入口文件
  • project.json 项目构建目标与配置

注意

此项目使用 ts#project 生成器创建，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ 针对特定项目/生成器的 Terraform 模块

      • …
    • 文件夹core/ 被 app 目录模块重用的通用模块

      • …
  • project.json 项目构建目标与配置

注意

此项目使用 terraform#project 生成器创建，因此配置了相同的构建目标。

生成器会根据您选择的 iacProvider 创建基础设施即代码：

CDK

• 文件夹packages/common/constructs/src

  • 文件夹app

    • 文件夹static-websites

      • <name>.ts 网站专属基础设施
  • 文件夹core

    • static-website.ts 通用 StaticWebsite 构造

Terraform

• 文件夹packages/common/terraform/src

  • 文件夹app

    • 文件夹static-websites

      • 文件夹<name>

        • <name>.tf 网站专属模块
  • 文件夹core

    • 文件夹static-website

      • static-website.tf 通用静态网站模块

开发 React 网站

React 文档 是学习 React 基础的良好起点。CloudScape 文档 则详细介绍了可用组件及其使用方法。

路由管理

创建路由/页面

默认配置的 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 文档。

运行时配置

基础设施配置通过运行时配置提供给网站，这使得网站可以访问部署时才能确定的参数（如 API 地址）。

基础设施配置

CDK

使用 RuntimeConfig CDK 构造管理配置。通过 @aws/nx-plugin 生成器（如 ts#trpc-api 和 py#fast-api）创建的 CDK 构造会自动向 RuntimeConfig 添加值。

网站 CDK 构造会将运行时配置部署为 S3 根目录下的 runtime-config.json 文件。

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

警告

必须确保在声明网站构造之前声明所有会向 RuntimeConfig 添加值的构造，否则这些值将不会出现在 runtime-config.json 中。

Terraform

Terraform 通过 runtime-config 模块管理配置。通过 @aws/nx-plugin 生成器（如 ts#trpc-api 和 py#fast-api）创建的 Terraform 模块会自动更新运行时配置。

网站 Terraform 模块会将运行时配置部署为 S3 根目录下的 runtime-config.json 文件。

packages/infra/src/main.tf

# 自动更新运行时配置
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"
}

# 自动部署 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]
}

警告

必须确保在声明网站模块之前声明所有会更新运行时配置的模块，并正确配置 depends_on 以保证执行顺序。

网站代码

在网站代码中，使用 useRuntimeConfig 钩子获取运行时配置值：

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

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

  // 在此访问运行时配置值
  const apiUrl = runtimeConfig.apis.MyApi;
};

本地运行时配置

运行本地开发服务器时，需要在 public 目录下放置 runtime-config.json 文件以使网站能获取后端 URL 等配置。

网站项目已配置 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 文件。

本地开发服务器

可通过 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 地址。

运行命令：

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：

• 若配置了 Cognito 认证（通过 CloudScape 网站认证生成器），登录流程将被跳过，请求不会携带认证头
• 如需启用登录认证，请部署基础设施后加载运行时配置

构建部署

使用 build 目标进行生产构建，该目标会执行类型检查、代码编译和打包：

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

网站部署

根据选择的 iacProvider，生成器会创建 CDK 或 Terraform 部署代码。

CDK

推荐使用 ts#infra 生成器 创建 CDK 应用。

使用 packages/common/constructs 中的构造进行部署：

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
4. 安全的 S3 访问控制
5. 自动部署网站文件及运行时配置

Terraform

推荐使用 terraform#project 生成器 创建 Terraform 项目。

使用 packages/common/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. 部署于 us-east-1 的 WAF
4. 安全的 S3 访问控制
5. 自动部署网站文件及运行时配置

注意

CloudFront 和 WAF 资源必须部署在 us-east-1 区域，请确保配置了对应 provider：

packages/infra/src/providers.tf

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