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

Tạo workspace của bạn@aws/nx-workspace

$ pnpm create @aws/nx-workspace my-project

$ yarn create @aws/nx-workspace my-project

$ npm create @aws/nx-workspace -- my-project

$ bun create @aws/nx-workspace my-project

Xây dựng lệnh của bạn8

workspaceBắt buộc

iac

containers

gitSecrets

true

mcp

true

module

catalog

true

preferInstallDependencies

true

Options

Tùy chọn của generator7 tùy chọn

iacenumMặc định: cdk: Nhà cung cấp IaC ưa thích.
cdkterraform
containersenumMặc định: 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).
inferdockerfinch
gitSecretsbooleanMặc định: true: Có cấu hình git-secrets để ngăn chặn commit thông tin xác thực AWS hay không.
mcpbooleanMặc định: true: Có cấu hình Nx Plugin cho AWS MCP server để sử dụng bởi các coding agent hay không.
moduleenumMặc định: esm: Định dạng module cho mã TypeScript và cấu hình được tạo ra.
esmcjs
catalogbooleanMặc định: 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.
preferInstallDependenciesbooleanMặc định: 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
biome.json Biome configuration for linting and formatting
aws-nx-plugin.config.mts Nx Plugin for AWS configuration
Thư mục.git-secrets/ Vendored git-secrets bash script for credential scanning
- …
.gitallowed Patterns git-secrets treats as false positives
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:

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

Để 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. 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 nx reset

yarn nx reset

npx nx reset

bunx nx reset

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

Parallelism

Các workspace mới đặt parallel trong nx.json, điều khiển số lượng tác vụ mà Nx chạy đồng thời:

{
  "parallel": 8
}

Giảm nó xuống nếu bạn đang build trên một máy có ít core hơn hoặc bộ nhớ hạn chế. Bạn cũng có thể ghi đè nó cho mỗi lần gọi:

pnpm nx run-many --target build --parallel=4

yarn nx run-many --target build --parallel=4

npx nx run-many --target build --parallel=4

bunx nx run-many --target build --parallel=4

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 add some-npm-package --filter my-project

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

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

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 build

yarn build

npm run build

bun build

Lint

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

pnpm lint

yarn lint

npm run lint

bun lint

Test

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

pnpm test

yarn test

npm run test

bun test

Dev

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

pnpm dev

yarn dev

npm run dev

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 nx sync

yarn nx sync

npx nx sync

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 nx <target> <project>

yarn nx <target> <project>

npx nx <target> <project>

bunx nx <target> <project>

Ví dụ:

pnpm nx build website

yarn nx build website

npx nx build website

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.

Cấu hình MCP

MCP server của plugin được cấu hình như một MCP server cấp project cho Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot và OpenAI Codex, vì vậy trợ lý lập trình của bạn có thể khám phá và chạy các generator của plugin mà không cần thiết lập gì. Cấu hình được commit cùng với workspace của bạn, mang lại cho mọi người trong nhóm cùng một thiết lập. Xóa bất kỳ cấu hình nào cho các trợ lý lập trình mà bạn và nhóm của bạn không sử dụng.

Git Secrets

Các workspace được thiết lập với 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.

Script được vendored vào workspace tại .git-secrets/git-secrets và chạy bởi hook .husky/pre-commit, vì vậy không có gì cần cài đặt — nhưng nó không có trong PATH của bạn, vì vậy hãy gọi nó bằng đường dẫn thay vì dùng git secrets.

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 (-a is the allowed flag)
bash .git-secrets/git-secrets --add -a -- 'my-regex-pattern'

# Allow a literal string, escaping special characters (-l is the literal flag)
bash .git-secrets/git-secrets --add -a -l -- 'my-literal+string'

# List what is currently allowed
git config --get-all secrets.allowed

Những cấu hình này được ghi lại trong git config cục bộ của bạn, vì vậy chúng chỉ áp dụng cho bản clone của riêng bạn. Để chia sẻ một suppression với nhóm của bạn, hãy thêm nó vào file .gitallowed ở root của repository — một regex tương thích egrep trên mỗi dòng, được khớp với <path>:<line-number>:<line-contents>:

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

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

export default {
  iac: {
    provider: 'cdk', // or 'terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
  packageManager: {
    catalogs: true, // or false
  },
} 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.
packageManager.catalogs — liệu các generator có ghi lại các phiên bản dependency trong catalog của package manager và tham chiếu chúng bằng protocol catalog: hay không (xem Single Version Policy). Đặt nó thành false để các generator ghi trực tiếp các version range vào package.json của mỗi project. Nó không có hiệu lực với npm, vốn không có catalog.

License generator thêm một key license vào cùng file này để cấu hình hành vi của chính nó.

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.