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.

Hướng Dẫn Full-Stack

Để có hướng dẫn chi tiết hơn về việc xây dựng ứng dụng full-stack, hãy xem Hướng Dẫn Dungeon Adventure.

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.0
  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 >= 10 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.

Thiết lập AI Assistant

Nếu bạn sử dụng AI Assistant như Kiro, Kiro CLI, Cursor, Claude Code hoặc Cline, bạn cũng có thể muốn cài đặt Nx Plugin for AWS MCP server.

Bước 1: Khởi Tạo Nx Workspace Mới

Chạy lệnh sau để tạo một Nx workspace với trình quản lý gói mà bạn chọn:

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

Chọn Nhà Cung Cấp IaC

Bạn sẽ được nhắc chọn nhà cung cấp infrastructure as code (IaC) ưa thích, có thể là CDK hoặc Terraform. Bạn có thể bỏ qua lời nhắc bằng cách chạy lệnh với --iac, ví dụ:

CDK

pnpm

pnpm create @aws/nx-workspace my-project --iac=cdk

yarn

yarn create @aws/nx-workspace my-project --iac=cdk

npm

npm create @aws/nx-workspace -- my-project --iac=cdk

bun

bun create @aws/nx-workspace my-project --iac=cdk

Terraform

pnpm

pnpm create @aws/nx-workspace my-project --iac=terraform

yarn

yarn create @aws/nx-workspace my-project --iac=terraform

npm

npm create @aws/nx-workspace -- my-project --iac=terraform

bun

bun create @aws/nx-workspace my-project --iac=terraform

Sau khi hoàn tất, di chuyển đến thư mục dự án:

cd my-project

Bước 2: Sử Dụng Generators để Tạo Khung Dự Án

Chúng ta sẽ thêm một tRPC API, React Website, Cognito Authentication, và CDK hoặc Terraform Infrastructure trong hướng dẫn bắt đầu nhanh này. 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.

Để tiết kiệm thời gian, bạn có thể sử dụng nút bên dưới để sao chép các lệnh tạo khung cho toàn bộ ứng dụng.

Loading the diagram…

Xây Dựng với AI

Nx Plugin for AWS MCP Server đã được cấu hình sẵn trong workspace của bạn, vì vậy bạn có thể yêu cầu AI coding agent yêu thích của mình như Kiro hoặc Claude xây dựng các dự án này cho bạn thay vì tự gõ các lệnh CLI.

Nếu không, hãy làm theo các bước dưới đây để chạy từng generator.

Thêm tRPC API

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive

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#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#api --name=demo-api --framework=trpc --auth=iam --no-interactive --dry-run

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
   • name: demo-api
   • framework: trpc
   • auth: iam
6. Nhấp Generate

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

Thêm React Website

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive

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 --name=demo-website --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website --name=demo-website --no-interactive --dry-run

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
   • name: demo-website
6. Nhấp Generate

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

Thêm Cognito Authentication

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive

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#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#website#auth --project=@my-project/demo-website --cognitoDomain=my-demo --no-interactive --dry-run

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
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Nhấp Generate

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive

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:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:connection --sourceProject=@my-project/demo-website --targetProject=@my-project/demo-api --no-interactive --dry-run

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
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Nhấp Generate

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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#infra --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --name=infra --no-interactive --dry-run

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
   • name: infra
6. Nhấp Generate

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive

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:terraform#project --name=infra --no-interactive --dry-run

yarn

yarn nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

npm

npx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

bun

bunx nx g @aws/nx-plugin:terraform#project --name=infra --no-interactive --dry-run

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
   • name: infra
6. Nhấp Generate

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.

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 { Stack, StackProps } from 'aws-cdk-lib';
import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
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:

# Include metrics tracking for @aws/nx-plugin usage
module "metrics" {
  source = "../../common/terraform/src/metrics"
}

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

Đâ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

Nếu bạn gặp bất kỳ lỗi lint 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

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.

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.

---

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!