跳转到内容
@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的Hook
      • 文件夹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下创建新<页面名称>.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 URL等部署时才能确定的参数。

    基础设施配置

    在CDK基础设施中，可使用RuntimeConfig构造来添加和获取配置。由@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');
    

        // 自动将运行时配置部署至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.httpApis.MyApi;
    };

    本地运行时配置

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

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

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

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

    本地开发服务器

    启动本地开发服务器前，请确保基础设施已部署且已加载本地运行时配置。

    随后可运行serve目标：

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

    构建部署

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