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

CloudScape 网站

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

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

使用方式

生成 CloudScape 网站

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

  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 静态资源目录
    • 文件夹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 构造体

    实现您的 CloudScape 网站

    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 文档。

    运行时配置

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

    基础设施

    RuntimeConfig CDK 构造体用于在基础设施中添加和获取配置。由 @aws/nx-plugin 生成的 CDK 构造体（如 tRPC API 和 FastAPI）会自动将适当的值添加到 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 文件中。

    网站代码

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

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

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

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

    本地运行时配置

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

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

    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 地址。

    运行以下命令启动：

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

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

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

    要为 serve-local 启用登录和身份验证，请部署基础设施并加载运行时配置。

    构建

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

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

    测试

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

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

    运行测试使用 test 目标：

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

    部署网站

    我们推荐使用 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');
      }
    }