Thêm vào Dự án Hiện có

Không phải dự án nào cũng bắt đầu với pnpm create @aws/nx-workspace. Nếu bạn đã có một Nx workspace — hoặc một monorepo mà bạn có thể thêm Nx vào — bạn có thể áp dụng @aws/nx-plugin từng bước mà không cần tạo lại dự án.

Yêu cầu

Bắt buộc

Git
Node >= 22 (Chúng tôi khuyến nghị sử dụng công cụ như NVM để quản lý các phiên bản node của bạn)
- xác minh bằng cách chạy node --version
UV >= 0.5.29
1. cài đặt Python 3.14 bằng cách chạy: uv python install 3.14.0
2. xác minh với uv python list --only-installed

Khuyến nghị

PNPM >= 11 (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
AWS Credentials được cấu hình cho tài khoản AWS mục tiêu của bạn là bắt buộc để triển khai ứng dụng của bạn (cũng như cho một số quy trình phát triển cục bộ).
Docker hoặc Finch >= 1.6.0 là bắt buộc cho một số trình tạo. Đối với Docker, multi-platform builds phải được thiết lập; Finch hỗ trợ multi-platform builds ngay từ đầu.
Terraform >= 1.12 là bắt buộc nếu bạn chọn sử dụng công cụ này cho infrastructure as code 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.

Thêm Nx vào dự án không dùng Nx

Nếu dự án của bạn chưa sử dụng Nx, hãy thêm nó trước với nx init. Đây là bước mà chính Nx sở hữu; plugin được xây dựng trên một workspace Nx đang hoạt động. Nó hoạt động trên một package đơn giản, một workspace npm/pnpm/yarn/bun, một Turborepo hoặc một monorepo Lerna:

pnpm dlx nx@23.1.1 init

yarn dlx nx@23.1.1 init

npx nx@23.1.1 init

bunx nx@23.1.1 init

Làm theo các hướng dẫn để thêm Nx vào workspace của bạn. Để biết thêm chi tiết, tham khảo Tài liệu Nx.

pnpm chỉ chạy install scripts cho các package được allow-list, và nx cần install script của nó — nếu không có, việc install mà nx init thực hiện có thể thất bại, để lại một placeholder set this to true or false trong pnpm-workspace.yaml. Allow-list nó trước khi chạy nx init:

allowBuilds:
  - nx

Dự án không dùng Node (Python, Go, Java, Rust, …)

Nx và plugin được phân phối dưới dạng các package npm, vì vậy một dự án không có công cụ Node.js cần một package.json gốc tối thiểu trước khi nx init có thể làm bất cứ điều gì hữu ích:

{
  "name": "my-project",
  "private": true,
  "type": "module"
}

Tạo file đó, sau đó chạy nx init và thêm plugin như bình thường. Công cụ ngôn ngữ hiện có của bạn không bị ảnh hưởng — các dự án Nx được tạo bởi plugin (bao gồm dự án Python) nằm cùng với code hiện có của bạn, và bạn có thể kết nối build hiện có của mình vào Nx từng bước.

Để đưa các dự án hiện có của bạn vào Nx, bạn có một vài tùy chọn tùy thuộc vào ngôn ngữ:

Ngôn ngữ có plugin Nx chính thức — Java (Gradle hoặc Maven) và .NET có các plugin chuyên dụng tự động suy luận các task của dự án. Thêm plugin liên quan, ví dụ nx add @nx/gradle, nx add @nx/maven hoặc nx add @nx/dotnet.
Ngôn ngữ có plugin cộng đồng — ví dụ Go (@nx-go/nx-go) hoặc Rust (@monodon/rust). Duyệt Nx Plugin Registry để tìm các plugin khác.
Bất kỳ ngôn ngữ nào khác — thêm một project.json vào mỗi dự án và định nghĩa các target của nó để chạy các lệnh build hiện có, để nx build <project> (và nx run-many) điều khiển chúng. Xem hướng dẫn workspace để biết cách thiết lập project.json và targets.

Dự án đơn package

Plugin được thiết kế cho monorepos — nó tạo mỗi dự án vào thư mục riêng của nó dưới packages/. Nếu bạn bắt đầu từ một dự án đơn package (một package.json ở gốc với source của bạn trực tiếp bên dưới nó, không có workspaces), di chuyển package hiện có của bạn vào packages/ trước khi áp dụng plugin để dự án của bạn nằm cùng với các dự án mà plugin tạo ra:

Tạo một thư mục packages/<your-package>/ và di chuyển source, package.json và tsconfig.json của bạn vào đó.
Tạo một package.json gốc mới hoạt động như workspace manifest thay vì một dự án:
package.json
```
{
  "name": "<your-workspace>",
  "private": true,
  "type": "module"
}
```
Khai báo workspace để package manager của bạn khám phá các dự án dưới packages/. Với pnpm, thêm một pnpm-workspace.yaml:
pnpm-workspace.yaml
```
packages:
  - packages/*
```
Với npm/yarn/bun, thêm một trường workspaces vào package.json gốc thay thế:
package.json
```
{
  "workspaces": ["packages/*"]
}
```
Chạy nx init (nếu bạn chưa chạy), sau đó thêm plugin.

Thêm plugin

Sử dụng nx add, cài đặt plugin ở phiên bản tương thích với cài đặt Nx của bạn và sau đó chạy generator init của nó để cấu hình workspace của bạn:

pnpm nx add @aws/nx-plugin

yarn nx add @aws/nx-plugin

npx nx add @aws/nx-plugin

bunx nx add @aws/nx-plugin

Khi hoàn tất, workspace của bạn đã sẵn sàng — chọn các generator bạn cần và bắt đầu tạo các dự án.

Generator này cấu hình gì

Thêm plugin thực hiện các thay đổi xác định mà một workspace cần để chạy các generator của plugin. Nó bảo toàn định dạng module của workspace: một workspace có package.json gốc với type: "module" vẫn là ESM, bất kỳ thứ gì khác vẫn là CommonJS, và code được tạo ra tuân theo. Nó không ghi đè các file hiện có, và bạn có thể cần thực hiện một số thay đổi thủ công sau bước này tùy thuộc vào cấu hình hiện có của bạn.

Nó tạo hoặc cập nhật các file sau:

aws-nx-plugin.config.mts ghi lại IaC provider bạn đã chọn (CDK hoặc Terraform) và container engine; các generator đọc iac.provider từ đây
nx.json đăng ký các sync generator (@nx/js:typescript-sync và @aws/nx-plugin:ts#sync) trên target compile để các tham chiếu dự án TypeScript luôn đồng bộ
tsconfig.json một config TypeScript gốc tham chiếu các dự án của workspace, mà TypeScript sync của Nx giữ cập nhật
tsconfig.base.json các compiler options được chia sẻ mà các dự án TypeScript của plugin mở rộng (xem bên dưới để biết nó chứa gì)
pnpm-workspace.yaml (chỉ pnpm) allow-list các build scripts mà các dependency của plugin cần (@swc/core, esbuild, nx, sharp)
package.json các script tiện lợi cho các task phổ biến, cộng với các dev dependencies @aws/nx-plugin, @aws/nx-plugin-mcp, nx, @nx/js, @nx/workspace, typescript và Biome
biome.json cấu hình formatter và linter Biome mặc định
.mcp.json cấu hình MCP server cho các coding agent được hỗ trợ trừ khi bị vô hiệu hóa (cũng bao gồm các tương đương .cursor/, .kiro/, .gemini/, .vscode/ và .codex/). Nó chạy @aws/nx-plugin-mcp của chính workspace, vì vậy server luôn khớp với phiên bản được cài đặt trong workspace của bạn

Cấu hình MCP server có thể bị vô hiệu hóa với --mcp=false.

Nhấp vào đây để xem các compiler options mà một tsconfig.base.json được tạo mang theo.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
iac	cdk \| terraform	cdk	Nhà cung cấp IaC ưa thích.
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	Container engine 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).
preferInstallDependencies	boolean	true	Có ưu tiên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để hoãn cài đặt khi thực hiện nhiều generator cùng lúc (việc cài đặt vẫn 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.

Khắc phục sự cố

`nx build <project>` không còn hoạt động cho một thư viện TypeScript hiện có

Lần chạy ts#project đầu tiên cấu hình plugin @nx/js/typescript để suy luận target build TypeScript là compile (plugin dành riêng build để điều phối lint, compile và test). Các thư viện hiện có dựa vào target build được suy luận cũng được suy luận là compile — chạy nx run <project>:compile, hoặc sử dụng nx run-many --target build,compile. Các thư viện có target build rõ ràng trong project.json của chúng không bị ảnh hưởng.

`The workspace is out of sync`

Các tham chiếu dự án TypeScript cần đồng bộ hóa. init đăng ký các sync generator; chạy:

pnpm nx sync

yarn nx sync

npx nx sync

bunx nx sync

`ERR_PNPM_IGNORED_BUILDS` trong quá trình install

pnpm bỏ qua install scripts cho các package không được allow-list. init allow-list các package mà công cụ của plugin cần (@swc/core, esbuild, nx, sharp) trong pnpm-workspace.yaml, nhưng lỗi có thể xảy ra trong chính nx add @aws/nx-plugin — trước khi init chạy. Chạy pnpm approve-builds và phê duyệt các package được liệt kê (hoặc thêm chúng dưới allowBuilds:), sau đó chạy lại install.

`nx sync` bị treo, hoặc `plugin worker ... exited before the connection was established`

Nếu hai phiên bản nx khác nhau có mặt trong cùng một cây node_modules (chạy npm ls nx để xác nhận), IPC plugin-worker của chúng bị deadlock. Generator init ghim devDependency nx gốc vào phiên bản mà các package @nx/* của chính plugin giải quyết, nhưng một lần install sau của một package @nx/* khác ở phiên bản patch khác có thể tái tạo sự không khớp. Căn chỉnh mọi mục nx và @nx/* trong package.json gốc của bạn thành một phiên bản duy nhất và cài đặt lại.

`ts.readConfigFile is not a function`

Workspace của bạn đã cài đặt TypeScript 7, mà Nx chưa hỗ trợ — các plugin của Nx dựa vào API compiler trong tiến trình của TypeScript, mà TypeScript 7 không còn cung cấp. Ghim typescript trong package.json gốc của bạn vào phiên bản mà plugin sử dụng (generator init cài đặt một phiên bản tương thích) và cài đặt lại.

`Recursive task invocation detected`

package.json gốc của bạn được đăng ký như một dự án Nx (nó có một key "nx", mà nx init thêm cho một repo đơn package) và mang một script build là nx run-many --target build. Nx sau đó suy luận một target build trên gốc gọi chính nó. Di chuyển source của bạn vào packages/<your-package>/ để gốc trở thành một workspace manifest thay vì một dự án — xem Dự án đơn package. (Các preset standalone của chính Nx tránh điều này bằng cách đặt "nx": { "includedScripts": [] } trên package gốc; bạn có thể làm tương tự như một giải pháp thay thế nhanh hơn.)

Lỗi TypeScript trong các dự án hiện có của bạn sau khi thêm plugin (`TS6059`, `TS7016`, `TS5011`, `NG4006`)

Các dự án được tạo của chính plugin mang các cài đặt TypeScript mà chúng cần trong tsconfig.lib.json của mỗi dự án, vì vậy chúng build bất kể tsconfig.base.json của bạn. Các lỗi này thay vào đó xuất hiện trong một dự án có sẵn của bạn kế thừa một tsconfig.base.json mà init đã tạo (với composite/emitDeclarationOnly/nodenext) nhưng không tương thích với các cài đặt đó — ví dụ, trình biên dịch Angular từ chối emitDeclarationOnly (NG4006), hoặc một dự án đặt outDir mà không có rootDir bây giờ cần một cái (TS5011). Thêm các override tsconfig cho mỗi dự án khai báo lại các options xung đột cho các dự án đó (ví dụ "rootDir": "src"), hoặc trỏ các dự án của plugin và các dự án của bạn vào các base config riêng biệt.

init không bao giờ viết lại một tsconfig.base.json hiện có, chính xác để nó không thể âm thầm phá vỡ các dự án kế thừa từ nó — giải quyết các sự không khớp này là một quyết định chỉ bạn mới có thể đưa ra cho codebase của mình.