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

Hướng dẫn này sẽ hướng dẫn bạn các bước cơ bản để cài đặt và sử dụng @aws/nx-plugin để xây dựng nhanh các dự án trên AWS.

Hướng dẫn full-stack

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

Yêu cầu trước

Các phụ thuộc toàn cục sau là cần thiết trước khi tiếp tục:

Bắt buộc

• Git
• Node >= 22 (Chúng tôi khuyên bạn nên sử dụng công cụ như NVM để quản lý các phiên bản node)
  • xác minh bằng cách chạy node --version
• PNPM >= 10 (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
• UV >= 0.5.29
  1. cài đặt Python 3.12 bằng cách chạy: uv python install 3.12.0
  2. xác minh bằng uv python list --only-installed
• Thông tin xác thực AWS được cấu hình cho tài khoản AWS đích của bạn (nơi ứng dụng của bạn sẽ được triển khai)

Khuyến nghị

• Docker là bắt buộc đối với một số trình tạo.
• Terraform >= 1.12 là bắt buộc nếu bạn chọn sử dụng công cụ này cho cơ sở hạ tầng dưới dạng mã 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 trợ lý AI

Nếu bạn sử dụng AI Assistant như Kiro, Amazon Q Developer, Cursor, Claude Code hoặc Cline, bạn cũng có thể muốn cài đặt Nx Plugin cho 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

npx create-nx-workspace@22.6.1 my-project --pm=pnpm --preset=@aws/nx-plugin --ci=skip --analytics=false --aiAgents

yarn

npx create-nx-workspace@22.6.1 my-project --pm=yarn --preset=@aws/nx-plugin --ci=skip --analytics=false --aiAgents

npm

npx create-nx-workspace@22.6.1 my-project --pm=npm --preset=@aws/nx-plugin --ci=skip --analytics=false --aiAgents

bun

npx create-nx-workspace@22.6.1 my-project --pm=bun --preset=@aws/nx-plugin --ci=skip --analytics=false --aiAgents

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 --iacProvider, ví dụ:

CDK

pnpm

npx create-nx-workspace@22.6.1 my-project --pm=pnpm --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --analytics=false --aiAgents

yarn

npx create-nx-workspace@22.6.1 my-project --pm=yarn --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --analytics=false --aiAgents

npm

npx create-nx-workspace@22.6.1 my-project --pm=npm --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --analytics=false --aiAgents

bun

npx create-nx-workspace@22.6.1 my-project --pm=bun --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --analytics=false --aiAgents

Terraform

pnpm

npx create-nx-workspace@22.6.1 my-project --pm=pnpm --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --analytics=false --aiAgents

yarn

npx create-nx-workspace@22.6.1 my-project --pm=yarn --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --analytics=false --aiAgents

npm

npx create-nx-workspace@22.6.1 my-project --pm=npm --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --analytics=false --aiAgents

bun

npx create-nx-workspace@22.6.1 my-project --pm=bun --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --analytics=false --aiAgents

Sau khi hoàn tất, điều hướng đế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 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 nào của các generators để nhanh chóng khởi tạo dự án của mình. Xem phần Guides trong thanh điều hướng bên trái để xem danh sách đầy đủ các tùy chọn.

Thêm tRPC API

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM

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#trpc-api --name=demo-api --auth=IAM --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

npm

npx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

bun

bunx nx g @aws/nx-plugin:ts#trpc-api --name=demo-api --auth=IAM --dry-run

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

Thêm React Website

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

CLI

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:ts#react-website --name=demo-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#react-website --name=demo-website --dry-run

yarn

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

npm

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

bun

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

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

Thêm Cognito Authentication

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#react-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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

yarn

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

npm

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

bun

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

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

Kết nối Frontend với Backend

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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 --dry-run

yarn

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

npm

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

bun

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

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

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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 --dry-run

yarn

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

npm

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

bun

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

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

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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 --dry-run

yarn

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

npm

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

bun

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

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 của bạn ở Local

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

pnpm

pnpm nx serve-local demo-website

yarn

yarn nx serve-local demo-website

npm

npx nx serve-local demo-website

bun

bunx nx serve-local demo-website

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 của bạn sẽ được phản ánh theo thời gian thực vì cả website local và API server đề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"
}

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

# 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à Deploy 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

Vùng bootstrap

CDK bootstrapping là bắt buộc 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 ban đầu

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 infra "my-project-sandbox/*"

yarn

yarn nx deploy infra "my-project-sandbox/*"

npm

npx nx deploy infra "my-project-sandbox/*"

bun

bunx nx deploy infra "my-project-sandbox/*"

Terraform

pnpm

pnpm nx apply infra

yarn

yarn nx apply infra

npm

npx nx apply infra

bun

bunx nx apply infra

Lên kế hoạch trước khi áp dụng

Lệnh này trước tiên sẽ chạy terraform plan để hiển thị những thay đổi sẽ được thực hiện, sau đó áp dụng các 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. Lấy tệp runtime-config.json:

   pnpm

   pnpm nx run demo-website:load:runtime-config

   yarn

   yarn nx run demo-website:load:runtime-config

   npm

   npx nx run demo-website:load:runtime-config

   bun

   bunx nx run demo-website:load:runtime-config

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!