React 网站

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

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

UX Provider

默认的 uxProvider 是 shadcn/ui。您也可以选择 Cloudscape 或 None（自带组件库）。

使用方式

生成 React 网站

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

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#website --framework=react --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 router 以实现类型安全的路由。
infra	cloudfront-s3 | none	cloudfront-s3	用于部署网站的基础设施类型。
iac	inherit | cdk | terraform	inherit	首选的 IaC 提供商。默认情况下,这将继承您的初始选择。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

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

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

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

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

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

    • 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，将会生成一个简单的 src/app.tsx 文件作为应用入口点，而不是 routes 目录。

基础设施

由于该生成器会根据您选择的 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 通用静态网站模块

架构

部署的网站具有以下架构：

安全头

CloudFront 分发应用响应头策略，在所有响应中设置 Strict-Transport-Security、X-Content-Type-Options、X-Frame-Options: DENY、Referrer-Policy 和 Content-Security-Policy。

默认会强制执行 Content-Security-Policy。它限制脚本和框架以缓解 XSS 和点击劫持攻击，同时允许 HTTPS 和 WSS 连接，以便网站可以调用仅在部署时才知道 URL 的 AWS 服务端点（如 API Gateway、Cognito 和 Bedrock AgentCore）。要调整策略（例如将 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 地址）。

基础设施配置

CDK

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

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

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

    // 网站构造可以在任意位置声明 — 运行时配置会延迟解析
    new MyWebsite(this, 'MyWebsite');

    // 自动向 RuntimeConfig 添加值
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

CDK网站构造

在 CDK 中，网站构造可以在堆栈的任意位置声明。运行时配置会在合成时延迟解析，因此无论声明顺序如何，所有值都会被包含。

Terraform

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

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

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

模块排序

必须确保在声明网站模块之前声明所有会更新运行时配置的模块，并正确配置 depends_on 以保证执行顺序，否则这些值将不会出现在 runtime-config.json 中。

网站代码

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

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

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

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

运行时配置

有关运行时配置如何存储在 AWS AppConfig 中，以及服务器端消费者（Lambda 函数、代理）如何检索配置的详细信息，请参阅 运行时配置 指南。

本地运行时配置

运行本地开发服务器时，需要在 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 文件。

本地开发服务器

本地开发的标准命令是 dev，它通过一条命令启动您的网站（以及您已连接的任何 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>

serve 目标也可用于需要控制应用程序在本地运行的部分与指向已部署 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 地址。

运行命令：

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 目标的项目运行该目标：

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

这会在一个命令中启动您的网站（以及任何其他具有 dev 目标的项目）的本地开发服务器。如果只想运行此网站，请使用其自己的 dev 目标（例如 nx dev <my-website>）。

模拟认证

在此模式下若未配置 runtime-config.json，如果配置了 Cognito 认证（通过 ts#website#auth 生成器），登录流程将被跳过，请求不会携带认证头。

如需启用 dev 的登录认证功能，请部署基础设施后加载运行时配置。

Dev 行为

使用 dev 运行时，您可以指定 API 所需的任何环境变量以指向其他已部署的 AWS 资源，例如：

pnpm

DYNAMODB_TABLE_NAME=xxxxx pnpm nx dev <my-website>

yarn

DYNAMODB_TABLE_NAME=xxxxx yarn nx dev <my-website>

npm

DYNAMODB_TABLE_NAME=xxxxx npx nx dev <my-website>

bun

DYNAMODB_TABLE_NAME=xxxxx bunx nx dev <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 文档。

运行测试：

pnpm

pnpm nx test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

网站部署

根据选择的 iacProvider，React 网站生成器会创建 CDK 或 Terraform 基础设施代码用于部署。

CDK

推荐使用 ts#infra 生成器 创建 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');
  }
}

该配置包含：

1. 托管静态文件的 S3 存储桶
2. 全球分发的 CloudFront
3. 安全防护的 WAF
4. 安全的 S3 访问控制
5. 自动部署网站文件及运行时配置

Terraform

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

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

WAF提供者区域

CloudFront 和 WAF 资源必须部署在 us-east-1 区域，需要配置 aws.us_east_1 provider。请确保您的 Terraform 配置包含此 provider：

packages/infra/src/providers.tf

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

连接

使用 connection 生成器将此项目与工作区中的其他项目集成。以下连接涉及此项目：

React to tRPC从 React 网站调用 tRPC API

React to FastAPI从 React 网站调用 Python FastAPI

React to Smithy API从 React 网站调用 Smithy API

React to Python Agent从 React 网站调用 Python Agent

React to TypeScript Agent从 React 网站调用 TypeScript Agent

React to AG-UI Agent通过 CopilotKit 从 React 网站调用公开 AG-UI 协议的 Agent