Trang Web React

Generator này tạo một trang web React mới với shadcn/ui được cấu hình mặc đị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.

UX Provider

uxProvider mặc định là shadcn/ui. Bạn cũng có thể chọn Cloudscape hoặc None (tự mang thư viện component của bạ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. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - ts#website
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#website --dry-run

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên của ứng dụng.
framework	react	react	Framework frontend sử dụng.
directory	string	packages	Thư mục của ứng dụng mới.
subDirectory	string	-	Thư mục con nơi dự án được đặt. Mặc định là tên dự án.
ux	none | cloudscape | shadcn	shadcn	Nhà cung cấp UX ưa thích.
tailwind	boolean	true	Bật TailwindCSS để tạo kiểu theo tiện ích.
tanstackRouter	boolean	true	Bật Tanstack router để định tuyến an toàn kiểu.
infra	cloudfront-s3 | none	cloudfront-s3	Loại hạ tầng để triển khai website của bạn.
iac	inherit | cdk | terraform	inherit	Nhà cung cấp IaC ưa thích. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

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ể và thanh điều hướng
  • Thư mụchooks

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

    • index.tsx Ví dụ route (hoặc trang) cho TanStack Router
  • styles.css Các style toàn cục
• vite.config.mts 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

Không dùng TanStack Router

Nếu bạn chọn không sử dụng TanStack Router, bạn sẽ nhận được một file src/app.tsx đơn giản làm điểm vào ứng dụng thay vì thư mục routes.

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

Dự án được tạo

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

Dự án được tạo

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

Kiến trúc

Trang web được triển khai có kiến trúc như sau:

Security Headers

CloudFront distribution áp dụng một response headers policy thiết lập Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy và Content-Security-Policy trên tất cả các response.

Một Content-Security-Policy mặc định được thực thi. Nó hạn chế các script và framing để giảm thiểu XSS và clickjacking, trong khi cho phép các kết nối HTTPS và WSS để trang web có thể gọi các endpoint dịch vụ AWS (như API Gateway, Cognito và Bedrock AgentCore) mà các URL chỉ được biết tại thời điểm triển khai. Để điều chỉnh policy (ví dụ để thắt chặt connect-src cho các origin cụ thể của bạn), hãy chỉnh sửa giá trị content_security_policy trong static-website.ts (CDK) hoặc static-website.tf (Terraform) được tạo của bạn.

runtime-config.json được phục vụ với Cache-Control: no-cache để trình duyệt luôn tải cấu hình mới nhất sau khi triển khai lại, thay vì sử dụng bản sao được lưu trong cache cũ.

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.

ux = cloudscape

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.

ux = shadcn

Bạn có thể tham khảo tài liệu shadcn/ui để 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 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 namespace connection của 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, MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // Website có thể được khai báo tại bất kỳ điểm nào — runtime config được resolve một cách lazy
    new MyWebsite(this, 'MyWebsite');

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

CDK Website Construct

Với CDK, construct website có thể được khai báo tại bất kỳ điểm nào trong stack của bạn. Cấu hình runtime được resolve một cách lazy tại thời điểm synth, vì vậy tất cả các giá trị sẽ được bao gồm bất kể thứ tự khai báo.

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 namespace connection của 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

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name
}

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

Thứ tự module

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

Cấu hình runtime

Để biết chi tiết về cách cấu hình runtime được lưu trữ trong AWS AppConfig và cách các consumer phía server (Lambda functions, agents) có thể truy xuất nó, hãy xem hướng dẫn Runtime Configuration.

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"

Tên stage tùy chỉnh

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

Lệnh chuẩn cho phát triển local là dev, khởi động trang web của bạn (và bất kỳ server local nào cho các API mà bạn đã kết nối với nó) bằng một lệnh duy nhất:

pnpm

pnpm nx dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

Target serve cũng có sẵn khi bạn cần kiểm soát mức độ ứng dụng của bạn chạy local so với việc trỏ đến cơ sở hạ tầng AWS đã triển khai. Để có cái nhìn tổng quan rộng hơn về phát triển local trên các dự án được kết nối, bao gồm cách dev hoạt động cho các dự án có nhiều thành phần, hãy xem hướng dẫn Local Development.

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 serve <my-website>

yarn

yarn nx serve <my-website>

npm

npx nx serve <my-website>

bun

bunx nx serve <my-website>

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ự”.

Dev Target

Target dev khởi động một local development server cho trang web của bạn (với Vite MODE được đặt thành local-dev), 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 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 dev <my-website>

yarn

yarn nx dev <my-website>

npm

npx nx dev <my-website>

bun

bunx nx dev <my-website>

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.

Script dev của Workspace

package.json gốc của workspace của bạn bao gồm một script dev chạy target dev cho mọi dự án có target đó:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Điều này khởi động local development server cho trang web của bạn (và bất kỳ dự án nào khác có target dev) trong một lệnh. Để chỉ chạy trang web này, hãy sử dụng target dev riêng của nó (ví dụ: nx dev <my-website>).

Xác thực giả lập

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 generator ts#website#auth), đă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 dev, hãy triển khai cơ sở hạ tầng của bạn và tải runtime config.

Hành vi Dev

Khi chạy với dev, bạn có thể chỉ định bất kỳ biến môi trường nào được yêu cầu bởi các API của bạn để trỏ đến các tài nguyên AWS đã triển khai khác, ví dụ:

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>

Lưu ý rằng các server API local của bạn sẽ chạy với thông tin đăng nhập AWS mà bạn đã cấu hình local.

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 chạy các target bundle, compile, test và lint, kiểm tra kiểu, đóng gói, testing và lint trang web của bạn.

pnpm

pnpm nx build <my-website>

yarn

yarn nx build <my-website>

npm

npx nx build <my-website>

bun

bunx nx build <my-website>

Target bundle sử dụng Vite để tạo một bundle production trong thư mục gốc dist/packages/<my-website>/bundle. Đây là artifact có thể triển khai được sử dụng bởi cơ sở hạ tầng trang web của bạn. Bạn có thể chạy nó độc lập:

pnpm

pnpm nx bundle <my-website>

yarn

yarn nx bundle <my-website>

npm

npx nx bundle <my-website>

bun

bunx nx bundle <my-website>

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 test <my-website>

yarn

yarn nx test <my-website>

npm

npx nx test <my-website>

bun

bunx nx test <my-website>

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

Vùng nhà cung cấp WAF

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

Kết nối

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

React to tRPCGọi API tRPC từ một trang web React

React to FastAPIGọi Python FastAPI từ một trang web React

React to Smithy APIGọi Smithy API từ một trang web React

React to Python AgentGọi Python Agent từ một trang web React

React to TypeScript AgentGọi TypeScript Agent từ một trang web React

React to AG-UI AgentGọi Agent hỗ trợ giao thức AG-UI từ một trang web React thông qua CopilotKit