Trang Web React

Generator này tạo một trang web React mới với CloudScape đã được cấu hình, cùng với cơ sở hạ tầng AWS CDK hoặc Terraform để triển khai trang web của bạn lên đám mây dưới dạng trang web tĩnh được lưu trữ trong S3, phân phối bởi CloudFront và được bảo vệ bởi WAF.

Ứng dụng được tạo ra sử dụng Vite làm công cụ xây dựng và đóng gói. Nó sử dụng TanStack Router cho định tuyến an toàn kiểu.

Ghi chú

Mặc dù generator này thiết lập cho bạn CloudScape, về cơ bản đây là một generator dự án React, và bạn có thể sửa đổi mã của mình để chuyển sang một hệ thống thiết kế hoặc thư viện component thay thế nếu muốn.

Cách sử dụng

Tạo một React Website

Bạn có thể tạo một React Website mới theo hai cách:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#react-website
5. Fill in the required parameters
6. Click 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

You can also perform a dry-run to see what files would be changed

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

Tùy chọn

Parameter	Type	Default	Description
name Required	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.

Kết quả từ Generator

Generator sẽ tạo cấu trúc dự án sau trong thư mục <directory>/<name>:

• index.html Điểm vào HTML
• public Tài nguyên tĩnh
• Thư mụcsrc

  • main.tsx Điểm vào ứng dụng với thiết lập React
  • config.ts Cấu hình ứng dụng (ví dụ: logo)
  • Thư mụccomponents

    • AppLayout Các component cho bố cục tổng thể CloudScape và thanh điều hướng
  • Thư mụchooks

    • useAppLayout.tsx Hook để điều chỉnh AppLayout từ các component lồng nhau
  • Thư mụcroutes

    • Thư mụcwelcome

      • index.tsx Ví dụ route (hoặc trang) cho @tanstack/react-router
  • styles.css Các style toàn cục
• vite.config.ts Cấu hình Vite và Vitest
• tsconfig.json Cấu hình TypeScript cơ bản cho mã nguồn và test
• tsconfig.app.json Cấu hình TypeScript cho mã nguồn
• tsconfig.spec.json Cấu hình TypeScript cho test

Cơ sở hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Ghi chú

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Ghi chú

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

Generator tạo infrastructure as code để triển khai trang web của bạn dựa trên iacProvider bạn đã chọn:

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcstatic-websites

      • <name>.ts Cơ sở hạ tầng cụ thể cho trang web của bạn
  • Thư mụccore

    • static-website.ts Construct StaticWebsite chung

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcstatic-websites

      • Thư mục<name>

        • <name>.tf Module cụ thể cho trang web của bạn
  • Thư mụccore

    • Thư mụcstatic-website

      • static-website.tf Module trang web tĩnh chung

Triển khai React Website của bạn

Tài liệu React là nơi tốt để bắt đầu học các kiến thức cơ bản về xây dựng với React. Bạn có thể tham khảo tài liệu CloudScape để biết chi tiết về các component có sẵn và cách sử dụng chúng.

Routes

Tạo một Route/Trang

Trang web CloudScape của bạn đi kèm với TanStack Router được cấu hình mặc định. Điều này giúp dễ dàng thêm các route mới:

1. Chạy Local Development Server
2. Tạo một file <page-name>.tsx mới trong src/routes, với vị trí của nó trong cây thư mục đại diện cho đường dẫn
3. Lưu ý rằng Route và RouteComponent được tự động tạo cho bạn. Bạn có thể bắt đầu xây dựng trang của mình tại đây!

Điều hướng giữa các Trang

Bạn có thể sử dụng component Link hoặc hook useNavigate để điều hướng giữa các trang:

import { Link, useNavigate } from '@tanstack/react-router';

export const MyComponent = () => {
  const navigate = useNavigate();

  const submit = async () => {
    const id = await ...
    // Sử dụng `navigate` để chuyển hướng sau một hành động bất đồng bộ
    navigate({ to: '/products/$id', { params: { id }} });
  };

  return (
    <>
      <Link to="/products">Cancel</Link>
      <Button onClick={submit}>Submit</Button>
    </>
  )
};

Để biết thêm chi tiết, hãy xem tài liệu TanStack Router.

Cấu hình Runtime

Cấu hình từ cơ sở hạ tầng của bạn được cung cấp cho trang web của bạn thông qua Runtime Configuration. Điều này cho phép trang web của bạn truy cập các chi tiết như URL API mà không được biết cho đến khi ứng dụng của bạn được triển khai.

Cơ sở hạ tầng

CDK

Construct CDK RuntimeConfig có thể được sử dụng để thêm và truy xuất cấu hình trong cơ sở hạ tầng CDK của bạn. Các construct CDK được tạo bởi các generator @aws/nx-plugin (như ts#trpc-api và py#fast-api) sẽ tự động thêm các giá trị phù hợp vào RuntimeConfig.

Construct CDK của trang web của bạn sẽ triển khai cấu hình runtime dưới dạng file runtime-config.json vào thư mục gốc của bucket S3 của bạn.

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

    // Tự động thêm các giá trị vào RuntimeConfig
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });

    // Tự động triển khai runtime config vào runtime-config.json
    new MyWebsite(this, 'MyWebsite');
  }
}

Chú ý

Bạn phải đảm bảo rằng bạn khai báo trang web của mình sau bất kỳ construct nào thêm vào RuntimeConfig, nếu không chúng sẽ bị thiếu trong file runtime-config.json của bạn.

Terraform

Với Terraform, cấu hình runtime được quản lý thông qua các module runtime-config. Các module Terraform được tạo bởi các generator @aws/nx-plugin (như ts#trpc-api và py#fast-api) sẽ tự động thêm các giá trị phù hợp vào cấu hình runtime.

Module Terraform của trang web của bạn sẽ triển khai cấu hình runtime dưới dạng file runtime-config.json vào thư mục gốc của bucket S3 của bạn.

packages/infra/src/main.tf

# Tự động thêm các giá trị vào runtime config
module "my_api" {
  source = "../../common/terraform/src/app/apis/my-api"
}

# Tự động triển khai runtime config vào runtime-config.json
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  # Đảm bảo API được triển khai trước để thêm vào runtime config
  depends_on = [module.my_api]
}

Chú ý

Bạn phải đảm bảo rằng bạn khai báo module trang web của mình sau bất kỳ module nào thêm vào cấu hình runtime và cấu hình depends_on phù hợp để đảm bảo thứ tự, nếu không chúng sẽ bị thiếu trong file runtime-config.json của bạn.

Mã Website

Trong trang web của bạn, bạn có thể sử dụng hook useRuntimeConfig để truy xuất các giá trị từ cấu hình runtime:

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

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

  // Truy cập các giá trị trong runtime config tại đây
  const apiUrl = runtimeConfig.apis.MyApi;
};

Runtime Config Local

Khi chạy local development server, bạn sẽ cần một file runtime-config.json trong thư mục public của bạn để trang web local của bạn biết các URL backend, cấu hình identity, v.v.

Dự án trang web của bạn được cấu hình với target load:runtime-config mà bạn có thể sử dụng để tải xuống file runtime-config.json từ một ứng dụng đã triển khai:

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"

Ghi chú

CDK

Nếu bạn thay đổi tiền tố cho tên stage trong file src/main.ts của dự án cơ sở hạ tầng, bạn sẽ cần cập nhật target load:runtime-config trong file project.json của trang web tương ứng.

Ngoài ra, cần lưu ý rằng target load:runtime-config giả định một stage duy nhất của ứng dụng của bạn được triển khai vào môi trường mà bạn có thông tin đăng nhập AWS. Bạn sẽ cần điều chỉnh lệnh nếu bạn triển khai nhiều stage vào cùng một tài khoản và khu vực.

Terraform

Đối với các dự án Terraform, target load:runtime-config sao chép file runtime-config.json được tạo sau lần terraform apply local gần nhất của bạn.

Local Development Server

Bạn có thể chạy một local development server bằng cách sử dụng target serve hoặc serve-local.

Target Serve

Target serve khởi động một local development server cho trang web của bạn. Target này yêu cầu bạn đã triển khai bất kỳ cơ sở hạ tầng hỗ trợ nào mà trang web tương tác với, và đã tải cấu hình runtime local.

Bạn có thể chạy target này với lệnh sau:

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

Target này hữu ích để làm việc với các thay đổi trang web trong khi trỏ đến các API và cơ sở hạ tầng khác đã được triển khai “thực sự”.

Target Serve Local

Target serve-local khởi động một local development server cho trang web của bạn (với Vite MODE được đặt thành serve-local), cũng như khởi động bất kỳ server local nào cho các API mà bạn đã kết nối trang web của mình thông qua API Connection generator.

Khi server trang web local của bạn được chạy thông qua target này, runtime-config.json được tự động ghi đè để trỏ đến các url API đang chạy local của bạn.

Bạn có thể chạy target này với lệnh sau:

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

Target này hữu ích khi bạn đang làm việc trên cả trang web và API của mình và muốn lặp lại nhanh chóng mà không cần triển khai cơ sở hạ tầng của bạn.

Khi chạy ở chế độ này và không có runtime-config.json, nếu bạn đã cấu hình Cognito Authentication (thông qua CloudScape Website Auth generator), đăng nhập sẽ được bỏ qua và các yêu cầu đến server local của bạn sẽ không bao gồm header xác thực.

Để bật đăng nhập và xác thực cho serve-local, hãy triển khai cơ sở hạ tầng của bạn và tải runtime config.

Xây dựng

Bạn có thể xây dựng trang web của mình bằng cách sử dụng target build. Điều này sử dụng Vite để tạo một bundle production trong thư mục gốc dist/packages/<my-website>/bundle, cũng như kiểm tra kiểu, biên dịch và lint trang web của bạn.

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

Testing

Testing trang web của bạn giống như viết test trong một dự án TypeScript tiêu chuẩn, vì vậy vui lòng tham khảo hướng dẫn dự án TypeScript để biết thêm chi tiết.

Đối với testing cụ thể của React, React Testing Library đã được cài đặt và có sẵn cho bạn sử dụng để viết test. Để biết thêm chi tiết về cách sử dụng, vui lòng tham khảo tài liệu React Testing Library.

Bạn có thể chạy test của mình bằng cách sử dụng target test:

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

Triển khai Trang web của bạn

Generator React website tạo infrastructure as code CDK hoặc Terraform dựa trên iacProvider bạn đã chọn. Bạn có thể sử dụng điều này để triển khai trang web của mình.

CDK

Để triển khai trang web của bạn, chúng tôi khuyên bạn nên sử dụng generator ts#infra để tạo một ứng dụng CDK.

Bạn có thể sử dụng construct CDK được tạo cho bạn trong packages/common/constructs để triển khai trang web của bạn.

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

Điều này thiết lập:

1. Một bucket S3 để lưu trữ các file trang web tĩnh của bạn
2. CloudFront distribution để phân phối nội dung toàn cầu
3. WAF Web ACL để bảo vệ bảo mật
4. Origin Access Control để truy cập S3 an toàn
5. Tự động triển khai các file trang web và cấu hình runtime

Terraform

Để triển khai trang web của bạn, chúng tôi khuyên bạn nên sử dụng generator terraform#project để tạo một dự án Terraform.

Bạn có thể sử dụng module Terraform được tạo cho bạn trong packages/common/terraform để triển khai trang web của bạn.

packages/infra/src/main.tf

# Triển khai website
module "my_website" {
  source = "../../common/terraform/src/app/static-websites/my-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }
}

Điều này thiết lập:

1. Một bucket S3 để lưu trữ các file trang web tĩnh của bạn
2. CloudFront distribution để phân phối nội dung toàn cầu
3. WAF Web ACL để bảo vệ bảo mật (được triển khai trong us-east-1)
4. Origin Access Control để truy cập S3 an toàn
5. Tự động triển khai các file trang web và cấu hình runtime

Ghi chú

Provider aws.us_east_1 là bắt buộc cho các tài nguyên CloudFront và WAF, phải được triển khai trong khu vực us-east-1. Đảm bảo cấu hình Terraform của bạn bao gồm provider này:

packages/infra/src/providers.tf

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