跳转到内容
@aws/nx-plugin
Blog

React 网站

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

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

使用方式

Section titled “使用方式”

生成 React 网站

Section titled “生成 React 网站”

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

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

    选项配置

    Section titled “选项配置”
    参数 类型 默认值 描述
    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.

    生成器输出

    Section titled “生成器输出”

    生成器将在 <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 配置

    生成器还会在 packages/common/constructs 目录下创建用于部署网站的 CDK 基础设施代码：

    • 文件夹src
      • 文件夹app
        • 文件夹static-websites
          • <name>.ts 网站专属基础设施
      • 文件夹core
        • static-website.ts 通用的 StaticWebsite 构造

    开发您的 React 网站

    Section titled “开发您的 React 网站”

    React 官方文档是学习 React 基础知识的理想起点。关于可用组件及其使用方法的详细信息，请参考 CloudScape 文档。

    路由管理

    Section titled “路由管理”

    创建路由/页面

    Section titled “创建路由/页面”

    默认配置的 CloudScape 网站已集成 TanStack Router，添加新路由非常简便：

    1. 启动本地开发服务器
    2. 在 src/routes 目录下新建 <页面名称>.tsx 文件，文件路径对应页面路径
    3. 系统会自动生成 Route 和 RouteComponent，您可在此开始构建页面！

    页面间导航

    Section titled “页面间导航”

    您可以使用 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 文档。

    运行时配置

    Section titled “运行时配置”

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

    基础设施

    Section titled “基础设施”

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

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

    网站代码

    Section titled “网站代码”

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

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

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

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

    本地运行时配置

    Section titled “本地运行时配置”

    运行本地开发服务器时，需要在 public 目录下放置 runtime-config.json 文件，以便本地网站获取后端地址、身份验证配置等信息。

    网站项目已配置 load:runtime-config 目标，可用于从已部署应用拉取 runtime-config.json 文件：

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

    如果修改了基础设施项目 src/main.ts 中的堆栈名称，需要同步更新网站项目 project.json 文件中 load:runtime-config 目标对应的堆栈名称。

    本地开发服务器

    Section titled “本地开发服务器”

    您可以使用 serve 或 serve-local 目标启动本地开发服务器。

    Serve 目标

    Section titled “Serve 目标”

    serve 目标启动网站的本地开发服务器。此目标要求已部署网站依赖的基础设施，并已加载本地运行时配置。

    运行以下命令启动：

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

    此目标适用于在指向”真实”已部署 API 和其他基础设施时进行网站修改。

    Serve Local 目标

    Section titled “Serve Local 目标”

    serve-local 目标会启动网站本地开发服务器（设置 Vite MODE 为 serve-local），同时启动通过 API 连接生成器 关联的本地 API 服务器。

    通过此目标运行时，runtime-config.json 会自动覆盖为指向本地运行的 API 地址。

    运行以下命令启动：

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

    此目标适用于需要同时开发网站和 API 并快速迭代的场景。

    在此模式下运行时，若未配置 runtime-config.json 且启用了 Cognito 身份验证（通过 CloudScape 网站身份验证生成器），将跳过登录流程且本地服务器请求不会包含身份验证头。

    如需在 serve-local 模式下启用登录和身份验证，请部署基础设施并加载运行时配置。

    构建

    Section titled “构建”

    使用 build 目标进行网站构建。该目标会使用 Vite 在根目录 dist/packages/<my-website>/bundle 下生成生产环境包，同时执行类型检查、编译和代码校验。

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

    测试

    Section titled “测试”

    网站测试与标准 TypeScript 项目测试类似，请参考 TypeScript 项目指南 获取详细信息。

    针对 React 的测试，项目已预装 React Testing Library。具体使用方法请参考 React Testing Library 文档。

    运行以下命令执行测试：

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

    部署网站

    Section titled “部署网站”

    我们推荐使用 TypeScript 基础设施生成器 创建 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');
      }
    }