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.

Mẹo

Để 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
• AWS Credentials đượ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.

Mẹo

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.0.2 my-project --pm=pnpm  --preset=@aws/nx-plugin --ci=skip --aiAgents

yarn

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

npm

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

bun

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

Mẹo

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.0.2 my-project --pm=pnpm  --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

yarn

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

npm

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

bun

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

Terraform

pnpm

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

yarn

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

npm

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

bun

npx create-nx-workspace@22.0.2 my-project --pm=bun  --preset=@aws/nx-plugin --iacProvider=Terraform --ci=skip --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. 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#trpc-api
5. Fill in the required parameters
   • name: demo-api
   • auth: IAM
6. Click 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

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

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. 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
   • name: demo-website
6. Click 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

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

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. 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#auth
5. Fill in the required parameters
   • project: @my-project/demo-website
   • cognitoDomain: my-demo
6. Click 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

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

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. 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 - api-connection
5. Fill in the required parameters
   • sourceProject: @my-project/demo-website
   • targetProject: @my-project/demo-api
6. Click Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

bunx nx g @aws/nx-plugin:api-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. 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#infra
5. Fill in the required parameters
   • name: infra
6. Click 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

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

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. 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 - terraform#project
5. Fill in the required parameters
   • name: infra
6. Click 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

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

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 run demo-website:serve-local

yarn

yarn nx run demo-website:serve-local

npm

npx nx run demo-website:serve-local

bun

bunx nx run demo-website:serve-local

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

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.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 nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

Mẹo

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 nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

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

CDK

pnpm

pnpm nx run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Mẹo

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 run infra:bootstrap

yarn

yarn nx run infra:bootstrap

npm

npx nx run infra:bootstrap

bun

bunx nx run infra:bootstrap

Mẹo

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 run infra:deploy my-project-sandbox/*

yarn

yarn nx run infra:deploy my-project-sandbox/*

npm

npx nx run infra:deploy my-project-sandbox/*

bun

bunx nx run infra:deploy my-project-sandbox/*

Terraform

pnpm

pnpm nx run infra:apply

yarn

yarn nx run infra:apply

npm

npx nx run infra:apply

bun

bunx nx run infra:apply

Mẹo

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 run demo-website:serve

   yarn

   yarn nx run demo-website:serve

   npm

   npx nx run demo-website:serve

   bun

   bunx nx run demo-website:serve

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!