Hướng Dẫn Bắt Đầu Nhanh

Hướng dẫn này sẽ giúp bạn làm quen với các bước cơ bản để cài đặt và sử dụng @aws/nx-plugin nhằm xây dựng các dự án trên AWS một cách nhanh chóng.

Yêu Cầu Trước Khi Bắt Đầu

Các phụ thuộc toàn cục sau đây cần được cài đặt trước khi tiếp tục:

Bắt buộc

• Git
• Node >= 22 (Chúng tôi khuyến nghị sử dụng công cụ như NVM để quản lý các phiên bản node của bạn)
  • xác minh bằng cách chạy node --version
• UV >= 0.5.29
  1. cài đặt Python 3.14 bằng cách chạy: uv python install 3.14
  2. xác minh với uv python list --only-installed

Khuyến nghị

• PNPM >= 11 (bạn cũng có thể sử dụng Yarn >= 4, Bun >= 1, hoặc NPM >= 11 nếu bạn muốn)
  • xác minh bằng cách chạy pnpm --version, yarn --version, bun --version hoặc npm --version
• AWS Credentials được cấu hình cho tài khoản AWS mục tiêu của bạn là bắt buộc để triển khai ứng dụng của bạn (cũng như cho một số quy trình phát triển cục bộ).
• Docker hoặc Finch >= 1.6.0 là bắt buộc cho một số trình tạo. Đối với Docker, multi-platform builds phải được thiết lập; Finch hỗ trợ multi-platform builds ngay từ đầu.
• Terraform >= 1.12 là bắt buộc nếu bạn chọn sử dụng công cụ này cho infrastructure as code thay vì CDK
  • xác minh bằng cách chạy terraform --version
• Nếu bạn đang sử dụng VSCode, chúng tôi khuyến nghị cài đặt Nx Console VSCode Plugin.

Bước 1: Tạo Workspace

Tạo một Nx workspace với trình quản lý gói mà bạn chọn, và mở thư mục nó tạo ra:

Tạo workspace của bạn@aws/nx-workspace

pnpm

$ pnpm create @aws/nx-workspace my-project

yarn

$ yarn create @aws/nx-workspace my-project

npm

$ npm create @aws/nx-workspace -- my-project

bun

$ bun create @aws/nx-workspace my-project

Xây dựng lệnh của bạn3

workspaceBắt buộc

iac

cdkterraform

containers

inferdockerfinch

cd my-project

Bạn sẽ được nhắc chọn nhà cung cấp infrastructure as code, có thể là CDK hoặc Terraform.

Bước 2: Xây Dựng Ứng Dụng Của Bạn

Chúng ta sẽ xây dựng một ứng dụng full-stack: một tRPC API, một React website, Cognito authentication, và CDK hoặc Terraform infrastructure. Yêu cầu trợ lý AI tạo khung cho bạn, hoặc tự chạy các generators — cả hai cách đều đạt được cùng một workspace.

Với AI

1. Mở workspace trong trợ lý AI coding của bạn.

   Các workspace mới đi kèm với MCP server của plugin đã được cấu hình sẵn cho Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot và OpenAI Codex, vì vậy trợ lý của bạn có thể tra cứu các generators của plugin và chạy chúng mà không cần thiết lập gì.

2. Yêu cầu ứng dụng:

   Prompt

   Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.

   Trợ lý của bạn khám phá các generators thông qua MCP server và chạy chúng, theo thứ tự mà các phụ thuộc của chúng cần. Xem xét các thay đổi nó thực hiện, sau đó tiếp tục ở Bước 3.

Với CLI

Chạy các generators tạo khung ứng dụng. Sử dụng nút bên dưới để sao chép tất cả, hoặc tự chạy từng cái như được mô tả bên dưới sơ đồ.

CDK

Loading the diagram…

Terraform

Loading the diagram…

Tùy thuộc vào loại dự án bạn đang xây dựng, bạn có thể chọn bất kỳ tổ hợp generators nào để nhanh chóng khởi tạo dự án của mình. Xem phần Generators trong thanh điều hướng bên trái để xem danh sách đầy đủ các tùy chọn, hoặc thử graph builder để xây dựng workspace của bạn một cách trực quan.

Thêm tRPC API

Chạy generator này@aws/nx-plugin:ts#api

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#api --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#api --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#api --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#api --no-interactive

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#api
5. Điền các tham số bắt buộc
6. Nhấp Generate

Tùy chọn cho bước này2

nameBắt buộc

framework

trpc

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

Lệnh này sẽ tạo API bên trong thư mục packages/demo-api.

Thêm React Website

Chạy generator này@aws/nx-plugin:ts#website

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

Tùy chọn cho bước này1

nameBắt buộc

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

Lệnh này tạo khung một React website mới trong packages/demo-website.

Thêm Cognito Authentication

Chạy generator này@aws/nx-plugin:ts#website#auth

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#website#auth --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#website#auth --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#website#auth --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#website#auth --no-interactive

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#auth
5. Điền các tham số bắt buộc
6. Nhấp Generate

Tùy chọn cho bước này1

projectBắt buộc

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

Lệnh này thiết lập cơ sở hạ tầng và mã React cần thiết để thêm Cognito Authentication vào website của bạn.

Kết Nối Frontend với Backend

Chạy generator này@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:connection --no-interactive

npm

$ npx nx g @aws/nx-plugin:connection --no-interactive

bun

$ bunx nx g @aws/nx-plugin:connection --no-interactive

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 - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

Tùy chọn cho bước này2

sourceProjectBắt buộc

targetProjectBắt buộc

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

Lệnh này cấu hình các providers cần thiết để đảm bảo website của bạn có thể gọi tRPC API.

Thêm Infrastructure

Thêm dự án infrastructure dựa trên nhà cung cấp IAC bạn đã chọn.

CDK

Chạy generator này@aws/nx-plugin:ts#infra

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:ts#infra --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:ts#infra --no-interactive

npm

$ npx nx g @aws/nx-plugin:ts#infra --no-interactive

bun

$ bunx nx g @aws/nx-plugin:ts#infra --no-interactive

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#infra
5. Điền các tham số bắt buộc
6. Nhấp Generate

Tùy chọn cho bước này1

nameBắt buộc

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

Lệnh này cấu hình một CDK App mà bạn có thể sử dụng để triển khai cơ sở hạ tầng của mình trên AWS.

Terraform

Chạy generator này@aws/nx-plugin:terraform#project

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:terraform#project --no-interactive

yarn

$ yarn nx g @aws/nx-plugin:terraform#project --no-interactive

npm

$ npx nx g @aws/nx-plugin:terraform#project --no-interactive

bun

$ bunx nx g @aws/nx-plugin:terraform#project --no-interactive

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 - terraform#project
5. Điền các tham số bắt buộc
6. Nhấp Generate

Tùy chọn cho bước này1

nameBắt buộc

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

Lệnh này cấu hình một dự án Terraform mà bạn có thể sử dụng để triển khai cơ sở hạ tầng của mình trên AWS.

Bước 3: Chạy Website và API Trên Máy Cục Bộ

Sử dụng lệnh sau để khởi động các dev server cục bộ cho website và các API được kết nối:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Website của bạn sẽ có sẵn tại http://localhost:4200.

Các thay đổi đối với cả website và API sẽ được phản ánh theo thời gian thực vì cả website và API server cục bộ đều sẽ hot-reload.

Try it: call the API from your website

Bước 4: Định Nghĩa Cloud Resources và Triển Khai lên AWS

CDK

Mở packages/infra/src/stacks/application-stack.ts và thêm đoạn mã sau:

import {
  DemoApi,
  DemoWebsite,
  UserIdentity,
} from '@my-project/common-constructs';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

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

    const identity = new UserIdentity(this, 'identity');
    const api = new DemoApi(this, 'api', {
      integrations: DemoApi.defaultIntegrations(this).build(),
    });
    api.grantInvokeAccess(identity.identityPool.authenticatedRole);

    new DemoWebsite(this, 'website');
  }
}

Đây là tất cả CDK chúng ta cần viết để triển khai ứng dụng full stack của mình.

Terraform

Mở packages/infra/src/main.tf và thêm đoạn mã sau:

# Deploy user identity
module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

# Shared asset bucket — stages Lambda deployment zips for every lambda / API module
module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Deploy API
module "demo_api" {
  source = "../../common/terraform/src/app/apis/demo-api"

  asset_bucket_name = module.asset_bucket.bucket_name
}

# Grant authenticated users access to invoke the API
resource "aws_iam_policy" "api_invoke_policy" {
  name        = "DemoApiInvokePolicy"
  description = "Policy to allow authenticated users to invoke the API"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = "execute-api:Invoke"
        Resource = "${module.demo_api.api_execution_arn}/*/*"
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_api_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.api_invoke_policy.arn
}

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

module "demo_website" {
  source = "../../common/terraform/src/app/static-websites/demo-website"

  providers = {
    aws.us_east_1 = aws.us_east_1
  }

  depends_on = [module.user_identity, module.demo_api]
}

# Print the website URL and user pool id when the deployment finishes
output "website_url" {
  value = module.demo_website.website_url
}

output "user_pool_id" {
  value = module.user_identity.user_pool_id
}

Đây là tất cả Terraform chúng ta cần viết để triển khai ứng dụng full stack của mình.

Build và Triển Khai Infrastructure

Tiếp theo, chạy lệnh sau để build dự án của bạn:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Sửa Lỗi Lint và Formatting

Nếu bạn gặp bất kỳ lỗi lint hoặc formatting nào, bạn có thể chạy lệnh sau để tự động sửa chúng.

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Workspace không đồng bộ

Nếu quá trình build báo The workspace is out of sync, hãy chấp nhận lời nhắc để đồng bộ workspace hoặc chạy trực tiếp lệnh đồng bộ sau trước khi thử lại build:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Lệnh này ghi các tham chiếu dự án TypeScript và các mục phụ thuộc package.json mà các import của bạn yêu cầu.

Bootstrap cơ sở hạ tầng của bạn:

CDK

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Bootstrap Regions

CDK bootstrapping được yêu cầu cho cả AWS region triển khai mục tiêu của bạn và us-east-1 để cho phép triển khai AWS WAF WebACL cho website. Nếu bạn đang triển khai ở nơi khác, hãy bootstrap us-east-1 cũng:

pnpm

pnpm nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

yarn

yarn nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

npm

npx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

bun

bunx nx run infra:bootstrap --args="aws://<account-id>/us-east-1"

Terraform

pnpm

pnpm nx bootstrap infra

yarn

yarn nx bootstrap infra

npm

npx nx bootstrap infra

bun

bunx nx bootstrap infra

Thiết Lập Một Lần

Terraform bootstrapping tạo một S3 bucket để lưu trữ các tệp state Terraform của bạn. Điều này chỉ cần thực hiện một lần cho mỗi tổ hợp AWS account/region.

Triển khai dự án của bạn:

CDK

pnpm

pnpm nx deploy-sandbox infra

yarn

yarn nx deploy-sandbox infra

npm

npx nx deploy-sandbox infra

bun

bunx nx deploy-sandbox infra

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

Plan Trước Khi Apply

Lệnh này sẽ chạy terraform plan trước để hiển thị những thay đổi sẽ được thực hiện, sau đó áp dụng những thay đổi đó để triển khai cơ sở hạ tầng của bạn.

Bước 5: Kiểm Tra Website với Cloud Resources Đã Triển Khai

1. Tải tệp runtime-config.json:

   pnpm

   pnpm nx load-runtime-config demo-website

   yarn

   yarn nx load-runtime-config demo-website

   npm

   npx nx load-runtime-config demo-website

   bun

   bunx nx load-runtime-config demo-website

2. Khởi động local website server

   pnpm

   pnpm nx serve demo-website

   yarn

   yarn nx serve demo-website

   npm

   npx nx serve demo-website

   bun

   bunx nx serve demo-website

Website của bạn sẽ có sẵn tại http://localhost:4200, và sẽ trỏ đến các tài nguyên bạn đã triển khai cho API và authentication.

Để đăng nhập, bạn sẽ cần tạo user trong Cognito user pool.

Click here for instructions using the AWS CLI

Website của bạn cũng được phục vụ từ CloudFront. Mở distribution domain name của nó (được in ra terminal của bạn sau khi triển khai) để sử dụng phiên bản chạy hoàn toàn trên AWS.

Chúc mừng! 🎉 Bạn đã xây dựng và triển khai thành công một ứng dụng full-stack bằng cách sử dụng @aws/nx-plugin!

Bước 6: Dọn Dẹp

Khi bạn đã hoàn tất, hãy xóa các tài nguyên bạn đã triển khai để tránh chi phí liên tục:

CDK

pnpm

pnpm nx destroy-sandbox infra

yarn

yarn nx destroy-sandbox infra

npm

npx nx destroy-sandbox infra

bun

bunx nx destroy-sandbox infra

Tài Nguyên Được Giữ Lại

Cognito user pool được tạo với tính năng bảo vệ xóa được bật, vì vậy nó không được xóa tự động. Xóa nó (và IAM role mà Cognito sử dụng để gửi tin nhắn SMS) thủ công nếu bạn không còn cần chúng nữa.

Terraform

pnpm

pnpm nx destroy infra

yarn

yarn nx destroy infra

npm

npx nx destroy infra

bun

bunx nx destroy infra

Tài Nguyên Được Giữ Lại

Cognito user pool được tạo với tính năng bảo vệ xóa được bật, vì vậy nó không được xóa tự động (lệnh destroy sẽ báo lỗi). Xóa nó (và IAM role mà Cognito sử dụng để gửi tin nhắn SMS) thủ công nếu bạn không còn cần chúng nữa.

Để xóa các tài nguyên bootstrap, làm theo hướng dẫn bên dưới:

CDK

Xóa bootstrap stack trong mọi region bạn đã bootstrap, bao gồm cả us-east-1. Điều này xóa các bootstrap roles và container image repository:

aws cloudformation delete-stack --stack-name CDKToolkit --region <region>

Asset Bucket

Asset bucket được giữ lại có chủ đích, vì vậy hãy xóa nó riêng.

Terraform

pnpm

pnpm nx bootstrap-destroy infra

yarn

yarn nx bootstrap-destroy infra

npm

npx nx bootstrap-destroy infra

bun

bunx nx bootstrap-destroy infra

Terraform State Của Bạn Cũng Bị Xóa

Lệnh này làm trống và xóa S3 bucket chứa Terraform state của bạn, vì vậy chỉ chạy nó khi bạn đã gỡ bỏ tất cả cơ sở hạ tầng đã triển khai.

---

Các Bước Tiếp Theo

• Dungeon Adventure Tutorial — xây dựng một trò chơi phiêu lưu dungeon AI full-stack, để có hướng dẫn chi tiết hơn hướng dẫn này.
• Workspaces — cách workspace của bạn được bố trí, và cấu hình mà các generators chia sẻ.
• Add to an Existing Project — áp dụng plugin trong codebase hiện có của bạn.