Workspace

Khi bạn tạo một workspace mới với @aws/nx-plugin, trình tạo preset sẽ thiết lập một Nx monorepo với các cấu hình mặc định hợp lý để xây dựng trên AWS.

Tạo 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

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
addTsPlugin	boolean	true	Có thêm ts plugin hay không.
iacProvider	string	CDK	Nhà cung cấp IaC ưa thích.
gitSecrets	boolean	true	Có cấu hình git-secrets để ngăn chặn commit thông tin xác thực AWS hay không.
containerEngine	string	infer	Container engine được sử dụng để build/push/login. 'infer' sẽ chọn docker nếu đã cài đặt, nếu không sẽ dùng finch (quay lại docker khi cả hai đều chưa được cài đặt).

Cấu trúc Workspace

• Thư mụcpackages/ Các dự án của bạn nằm ở đây

  • …
• package.json Root package.json cho monorepo của bạn
• nx.json Cấu hình Nx (common targets, sync generators, caching)
• tsconfig.base.json Cấu hình TypeScript gốc
• aws-nx-plugin.config.mts Cấu hình Nx Plugin for AWS
• Thư mục.git-secrets/ Script bash git-secrets được đóng gói để quét thông tin xác thực

  • …
• Thư mục.husky/ Git hooks

  • …

Nx

Nx là một hệ thống build không phụ thuộc ngôn ngữ cho monorepo, quản lý các phụ thuộc giữa các dự án được viết bằng bất kỳ ngôn ngữ lập trình nào và các tác vụ để build chúng. Bạn có thể tìm hiểu thêm trên trang web Nx.

Projects

Một Nx monorepo được tạo thành từ một hoặc nhiều dự án, mỗi dự án có một tệp project.json. Tệp project.json định nghĩa các tác vụ của dự án, được gọi là targets, xác định cách một dự án được build, chạy cục bộ, test, v.v. Nó cũng định nghĩa các phụ thuộc giữa các target trong hoặc giữa các dự án.

Ví dụ, một project.json có thể định nghĩa một target build phụ thuộc vào tất cả các dự án upstream được build trước:

packages/my-project/project.json

{
  "name": "@my-workspace/my-project",
  "targets": {
    "build": {
      "executor": "@nx/js:tsc",
      "dependsOn": ["^build"]
    },
    "test": {
      "command": "vitest run"
    }
  }
}

Mẹo

Đối với các dự án bằng ngôn ngữ không được hỗ trợ trực tiếp bởi Nx Plugin for AWS, bạn thường có thể tìm thấy một trình tạo trong Nx Plugin Registry để hỗ trợ. Tuy nhiên, việc thêm một dự án bằng bất kỳ ngôn ngữ nào vào monorepo của bạn rất đơn giản — chỉ cần thêm một tệp project.json và định nghĩa target build của nó để chạy lệnh build cụ thể cho dự án của ngôn ngữ đó.

Để biết chi tiết về cách thiết lập các dự án TypeScript và Python, hãy tham khảo hướng dẫn trình tạo ts#project và py#project.

Caching

Nx lưu cache đầu ra của các target đã thực thi trước đó và phát lại chúng khi các đầu vào không thay đổi. Điều này tăng tốc đáng kể việc build, test và linting — đặc biệt trong CI. Nếu bạn gặp phải hành vi cũ hoặc không mong đợi, hãy đặt lại cache với:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

Để biết thêm chi tiết, xem tài liệu caching của Nx.

Single Version Policy

Thiết lập monorepo mặc định sử dụng single version policy cho cả các dự án dựa trên Node và Python.

Điều này có nghĩa là tất cả các dự án trong monorepo của bạn sử dụng cùng một phiên bản của các phụ thuộc theo mặc định, giảm các vấn đề liên quan đến các package trong cùng một monorepo gặp phải vấn đề không khớp phiên bản.

Từ góc độ Node, điều này có nghĩa là một lockfile duy nhất ở thư mục gốc với một node_modules duy nhất chứa tất cả các phụ thuộc. Nếu bạn cần thêm một phụ thuộc mới, hãy thêm nó vào package.json ở thư mục gốc.

Từ góc độ Python, điều này có nghĩa là một .venv duy nhất ở thư mục gốc của monorepo với tất cả các phụ thuộc được cài đặt vào đó. Mỗi dự án Python có pyproject.toml riêng, nhưng các phiên bản của các phụ thuộc đó được quản lý bởi UV workspace và sau đó được ghi ra tệp uv.lock ở thư mục gốc.

Các Lệnh Thông Dụng

Build

Build tất cả các dự án trong workspace:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Lint

Lint và tự động sửa tất cả các dự án:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Test

Chạy test trên tất cả các dự án:

pnpm

pnpm test

yarn

yarn test

npm

npm run test

bun

bun test

Dev

Nếu bạn có một website, khởi động nó và tất cả các component được kết nối cục bộ:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Sync

Chạy bất kỳ sync generators nào, ví dụ như đồng bộ hóa các tham chiếu dự án TypeScript (tham khảo hướng dẫn trình tạo ts#project để biết thêm chi tiết):

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Chạy Các Target Cụ Thể

Bạn có thể chạy các target cụ thể cho các dự án cụ thể với:

pnpm

pnpm nx <target> <project>

yarn

yarn nx <target> <project>

npm

npx nx <target> <project>

bun

bunx nx <target> <project>

Ví dụ:

pnpm

pnpm nx build website

yarn

yarn nx build website

npm

npx nx build website

bun

bunx nx build website

Điều này sẽ chạy target đã chọn cũng như các target mà nó phụ thuộc vào.

Những Gì Được Bao Gồm

Linting

Các workspace mới được cấu hình với ESLint để phân tích tĩnh và Prettier để định dạng code. Chạy lint áp dụng cả hai cho tất cả các dự án.

Git Secrets

Các workspace mới bao gồm git-secrets pre-commit hooks để quét các tệp đã staged tìm các mẫu thông tin xác thực AWS trước mỗi commit. Điều này ngăn chặn việc vô tình commit các access key, secret key và các giá trị nhạy cảm khác.

Loại Bỏ False Positives

Các mẫu trong git-secrets sử dụng biểu thức chính quy tương thích egrep. Nếu git-secrets chặn một commit không chứa thông tin xác thực thực sự:

# Cho phép một mẫu regex cụ thể
git secrets --add --allowed 'my-regex-pattern'

# Cho phép một chuỗi theo nghĩa đen (các ký tự đặc biệt được escape)
git secrets --add --allowed --literal 'my-literal+string'

Bạn cũng có thể tạo một tệp .gitallowed ở thư mục gốc của repository với một regex tương thích egrep mỗi dòng (chia sẻ với nhóm của bạn qua version control):

.gitallowed

# Allow test fixtures
tests/fixtures/.*
# Allow a specific string
EXAMPLE[A-Z]{16}

Để biết đầy đủ chi tiết về quản lý các mẫu, xem tài liệu git-secrets.

Cấu Hình Nx Plugin for AWS

Workspace đi kèm với một tệp aws-nx-plugin.config.mts ở thư mục gốc. Các trình tạo đọc tệp này để chọn các giá trị mặc định hợp lý để bạn không phải truyền cùng các flag mỗi lần. Hai cài đặt đặc biệt hữu ích:

// aws-nx-plugin.config.mts
import { AwsNxPluginConfig } from '@aws/nx-plugin';

export default {
  iac: {
    provider: 'CDK', // or 'Terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
} satisfies AwsNxPluginConfig;

• iac.provider — nhà cung cấp infrastructure-as-code mặc định (CDK hoặc Terraform) được sử dụng bởi các trình tạo phát ra cơ sở hạ tầng (ví dụ: ts#infra, ts#trpc-api, py#fast-api). Các trình tạo chấp nhận flag --iacProvider mặc định là Inherit, đọc giá trị này.
• containers.engine — container CLI (docker hoặc finch) được tích hợp vào các lệnh build/push/login được tạo ra. Các bản build CDK image-asset cũng sử dụng giá trị này thông qua biến môi trường CDK_DOCKER. Xem hướng dẫn Docker bundling để biết chi tiết.

Bạn có thể chỉnh sửa bất kỳ cài đặt nào bất cứ lúc nào — các lần chạy trình tạo tiếp theo sẽ sử dụng giá trị mới.