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 của mình.

Yêu cầu

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 >= 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
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 bằng uv python list --only-installed
Thông tin xác thực AWS đượ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. Multi-platform builds phải được thiết lập.
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.

Thêm Nx vào dự án không phải 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à Nx tự quản lý; plugin được xây dựng trên một Nx workspace đang hoạt động. Nó hoạt động trên một package đơn giản, một npm/pnpm/yarn/bun workspace, một Turborepo hoặc một Lerna monorepo:

pnpm dlx nx@23.0.2 init

yarn dlx nx@23.0.2 init

npx nx@23.0.2 init

bunx nx@23.0.2 init

Làm theo các lời nhắc để 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 script cho các package được cho phép, và nx cần install script của nó — nếu không có nó, việc cài đặt 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. Cho phép nó trước khi chạy nx init:

allowBuilds:
  - nx

Dự án không phải Node (Python, Go, Java, Rust, …)

Nx và plugin được phân phối dưới dạng npm package, 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ư thường lệ. 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ạnh 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 ra 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 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à các target.

Dự án đơn package

Plugin được thiết kế cho monorepo — 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ó workspace), hãy 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ạnh các dự án mà plugin tạo ra:

Tạo 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, ví dụ { "name": "<your-workspace>", "private": true }.
Khai báo workspace: đối với pnpm, thêm pnpm-workspace.yaml với packages: ['packages/*']; đối với npm/yarn/bun, thêm "workspaces": ["packages/*"] vào package.json gốc mới.
Chạy nx init (nếu bạn chưa chạy), sau đó thêm plugin.

Thêm plugin

Sử dụng nx add, lệnh này 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ấ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 nó hoàn thành, workspace của bạn đã sẵn sàng — chọn các generator bạn cần và bắt đầu tạo dự án.

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

Thêm plugin thực hiện các thay đổi xác định mà 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 điều đó. 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 cấu hình TypeScript gốc tham chiếu đến các dự án của workspace, mà TypeScript sync của Nx giữ cập nhật
tsconfig.base.json các tùy chọn compiler được chia sẻ mà các dự án TypeScript của plugin mở rộng (xem bên dưới để biết nó mang gì)
pnpm-workspace.yaml (chỉ pnpm) cho phép các build script 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 tác vụ phổ biến, cộng với các dev dependency 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/)

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 tùy chọn compiler mà 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ố

`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 cài đặt

pnpm bỏ qua các install script cho các package không có trong danh sách cho phép. init cho phép các script 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 quá trì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 cài đặt.

`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 cố định 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 việc cài đặt sau này 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. Cố định 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ý là một dự án Nx (nó có 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 ra 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 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 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 bởi plugin mang các cài đặt TypeScript mà chúng cần trong tsconfig.lib.json của từng dự án, vì vậy chúng build bất kể tsconfig.base.json của bạn. Những lỗi này xuất hiện thay vào đó 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 từng dự án khai báo lại các tùy chọn 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 những sự không khớp này là quyết định chỉ bạn mới có thể đưa ra cho codebase của mình.