Workspace

Khi bạn tạo một workspace mới với @aws/nx-plugin, preset generator 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 một 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

Options

Tham số	Kiểu	Mặc định	Mô tả
iac	cdk | terraform	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.
mcp	boolean	true	Có cấu hình Nx Plugin cho AWS MCP server để sử dụng bởi các coding agent hay không.
containers	infer | docker | finch	infer	Công cụ container để sử dụng cho build/push/login. 'infer' chọn docker nếu đã cài đặt, nếu không thì chọn finch (quay lại docker khi cả hai đều chưa cài đặt).
module	esm | cjs	esm	Định dạng module cho mã TypeScript và cấu hình được tạo ra.
catalog	boolean	true	Liệu các generator có ghi lại phiên bản phụ thuộc trong catalog của trình quản lý gói (pnpm/yarn/bun) hay không, giữ một nguồn duy nhất cho các phiên bản. Khi là false, các phụ thuộc sẽ được ghi trực tiếp vào package.json của từng dự án và việc giữ các phiên bản đồng bộ là trách nhiệm của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Cấu trúc Workspace

• Thư mụcpackages/ Your projects live here

  • …
• package.json Root package.json for your monorepo
• nx.json Nx configuration (common targets, sync generators, caching)
• tsconfig.base.json Root TypeScript configuration
• aws-nx-plugin.config.mts Nx Plugin for AWS configuration
• Thư mục.git-secrets/ Vendored git-secrets bash script for credential scanning

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

  • …
• .mcp.json Nx Plugin for AWS MCP server configuration for Claude Code
• .cursor/mcp.json …and for Cursor
• .kiro/settings/mcp.json …and for Kiro
• .gemini/settings.json …and for Gemini CLI
• .vscode/mcp.json …and for GitHub Copilot
• .codex/config.toml …and for OpenAI Codex

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ụ để xây dựng 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 project, mỗi project có một file project.json. File project.json định nghĩa các tác vụ của project, được gọi là target, xác định cách một project được xây dựng, chạy cục bộ, kiểm thử, 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 project.

Ví dụ, một project.json có thể định nghĩa một build target phụ thuộc vào tất cả các project upstream được xây dựng 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 project bằng ngôn ngữ không được Nx Plugin for AWS hỗ trợ trực tiếp, bạn thường có thể tìm thấy một generator trong Nx Plugin Registry để hỗ trợ. Tuy nhiên, việc thêm một project 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 file project.json và định nghĩa build target của nó để chạy lệnh build cụ thể cho một project của ngôn ngữ đó.

Để biết chi tiết về cách các project TypeScript và Python được thiết lập, hãy tham khảo hướng dẫn generator 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ể quá trình 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 bằng:

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 project dựa trên Node và Python.

Điều này có nghĩa là tất cả các project trong monorepo của bạn sử dụng cùng một phiên bản của các dependency 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 ở root, với các dependency được cài đặt một lần và liên kết vào mỗi project. Mỗi project Node khai báo các runtime dependency mà source code của nó import trong package.json riêng của nó, trong khi các công cụ build/test dùng chung nằm trong devDependencies của package.json ở root. Thêm một runtime dependency của project bằng cách cài đặt nó vào project đó:

pnpm

pnpm add some-npm-package --filter my-project

yarn

yarn workspace @my-scope/my-project add some-npm-package

npm

npm install --legacy-peer-deps some-npm-package -w packages/my-project

bun

bun add some-npm-package --cwd packages/my-project

Đối với các package manager có hỗ trợ catalog (pnpm, yarn và bun), các phiên bản dependency được ghi lại trong catalog và tham chiếu bằng protocol catalog:, giữ một nguồn chân lý duy nhất cho các phiên bản trên mọi package.json của mỗi project. Đối với npm workspaces, chúng tôi khuyên dùng syncpack để căn chỉnh các phiên bản được khai báo trên nhiều file package.json.

Từ góc độ Python, điều này có nghĩa là một .venv duy nhất ở root của monorepo với tất cả các dependency được cài đặt vào đó. Mỗi project Python có pyproject.toml riêng của nó, nhưng các phiên bản của những dependency đó được quản lý bởi UV workspace và sau đó được ghi ra file uv.lock ở root.

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

Build

Build tất cả các project 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 project:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Test

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

pnpm

pnpm test

yarn

yarn test

npm

npm run test

bun

bun test

Dev

Khởi động tất cả các development server cục bộ trên workspace của bạn:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

Xem hướng dẫn Local Development để biết thêm chi tiết.

Sync

Chạy bất kỳ sync generator nào, ví dụ như đồng bộ hóa các TypeScript project reference (tham khảo hướng dẫn generator 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 project cụ thể bằng:

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 được 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 Biome cho phân tích tĩnh và định dạng code. Chạy lint kiểm tra tất cả các project để tìm vấn đề, và lint --configuration=fix tự động sửa chúng.

Git Secrets

Các workspace mới bao gồm các pre-commit hook của git-secrets quét các file được staged để tìm các mẫu credential của 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 Positive

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 credential thực:

# Allow a specific regex pattern
git secrets --add --allowed 'my-regex-pattern'

# Allow a literal string (special characters are escaped)
git secrets --add --allowed --literal 'my-literal+string'

Bạn cũng có thể tạo một file .gitallowed ở root của repository với một regex tương thích egrep trên mỗi dòng (được chia sẻ với nhóm của bạn thông 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 file aws-nx-plugin.config.mts ở root. Các generator đọc file 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 — infrastructure-as-code provider mặc định (cdk hoặc terraform) được sử dụng bởi các generator phát ra infrastructure (ví dụ: ts#infra, ts#api, py#api). Các generator chấp nhận flag --iac 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 CDK image-asset build cũng nhận điều 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 generator tiếp theo sẽ nhận giá trị mới.