Add to an Existing Project

Not every project starts with pnpm create @aws/nx-workspace. If you already have an Nx workspace — or a monorepo you can add Nx to — you can adopt @aws/nx-plugin incrementally without recreating your project.

Tip

You can use your agentic coding tool of choice to add the plugin for you, using the MCP server. Try the prompt:

Add the Nx Plugin for AWS to this project.

Prerequisites

Required

• Git
• Node >= 22 (We recommend using something like NVM to manage your node versions)
  • verify by running node --version
• PNPM >= 11 (you can also use Yarn >= 4, Bun >= 1, or NPM >= 10 if you prefer)
  • verify by running pnpm --version, yarn --version, bun --version or npm --version
• UV >= 0.5.29
  1. install Python 3.14 by running: uv python install 3.14.0
  2. verify with uv python list --only-installed
• AWS Credentials configured to your target AWS account (where your application will be deployed)

Recommended

• Docker is required for some generators. Multi-platform builds must be set up.
• Terraform >= 1.12 is required if you choose to use this for infrastructure as code instead of CDK
  • verify by running terraform --version
• If you are using VSCode, we recommend installing the Nx Console VSCode Plugin.

AI Assistant Setup

If you use an AI Assistant such as Kiro, Kiro CLI, Cursor, Claude Code or Cline, you may also wish to install the Nx Plugin for AWS MCP server.

Before you start

Save and commit all in-progress work first, so the changes made at each step can be reviewed — and reverted — at any point.

Adding Nx to a non-Nx project

If your project doesn’t use Nx yet, add it first with nx init. This is a step Nx itself owns; the plugin builds on top of a working Nx workspace. It works on a plain package, an npm/pnpm/yarn/bun workspace, a Turborepo or a Lerna monorepo:

pnpm

pnpm dlx nx@23.0.2 init

yarn

yarn dlx nx@23.0.2 init

npm

npx nx@23.0.2 init

bun

bunx nx@23.0.2 init

Follow the prompts to add Nx to your workspace. For more details refer to the Nx Documentation.

pnpm workspaces

pnpm only runs install scripts for allow-listed packages, and nx needs its install script — without it, the install nx init performs can fail, leaving a set this to true or false placeholder in pnpm-workspace.yaml. Allow-list it before running nx init:

pnpm-workspace.yaml

allowBuilds:
  - nx

Non-Node projects (Python, Go, Java, Rust, …)

Nx and the plugin are distributed as npm packages, so a project with no Node.js tooling needs a minimal root package.json before nx init can do anything useful:

package.json

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

Create that file, then run nx init and add the plugin as usual. Your existing language tooling is untouched — Nx projects generated by the plugin (including Python projects) live alongside your existing code, and you can wire your existing build into Nx incrementally.

To bring your existing projects under Nx, you have a few options depending on the language:

• Languages with an official Nx plugin — Java (Gradle or Maven) and .NET have dedicated plugins that infer your projects’ tasks automatically. Add the relevant one, e.g. nx add @nx/gradle, nx add @nx/maven or nx add @nx/dotnet.
• Languages with a community plugin — for example Go (@nx-go/nx-go) or Rust (@monodon/rust). Browse the Nx Plugin Registry for others.
• Any other language — add a project.json to each project and define its targets to run your existing build commands, so nx build <project> (and nx run-many) drive them. See the workspace guide for how project.json and targets are set up.

Single-package projects

The plugin is designed for monorepos — it generates each project into its own directory under packages/. If you’re starting from a single-package project (one package.json at the root with your source directly beneath it, no workspaces), move your existing package into packages/ before adopting the plugin so your project sits alongside the ones the plugin generates:

1. Create a packages/<your-package>/ directory and move your source, package.json and tsconfig.json into it.

2. Create a new root package.json that acts as the workspace manifest rather than a project itself:

   package.json

   {
     "name": "<your-workspace>",
     "private": true,
     "type": "module"
   }

3. Declare the workspace so your package manager discovers projects under packages/. For pnpm, add a pnpm-workspace.yaml:

   pnpm-workspace.yaml

   packages:
     - packages/*

   For npm/yarn/bun, add a workspaces field to the root package.json instead:

   package.json

   {
     "workspaces": ["packages/*"]
   }

4. Run nx init (if you haven’t), then add the plugin.

Package manager

The plugin’s projects are generated under a packages/ directory. pnpm reads workspace globs from pnpm-workspace.yaml; other package managers read the workspaces field of the root package.json — init updates whichever your workspace uses.

Adding the plugin

Use nx add, which installs the plugin at a version compatible with your Nx installation and then runs its init generator to configure your workspace:

pnpm

pnpm nx add @aws/nx-plugin

yarn

yarn nx add @aws/nx-plugin

npm

npx nx add @aws/nx-plugin

bun

bunx nx add @aws/nx-plugin

Once it completes, your workspace is ready — choose the generators you need and start generating projects.

What this generator configures

Adding the plugin makes the deterministic changes a workspace needs to run the plugin’s generators. It preserves your workspace’s module format: a workspace whose root package.json has type: "module" stays ESM, anything else stays CommonJS, and generated code follows suit. It does not overwrite existing files, and you may need to make some manual changes following this step depending on your existing configuration.

It creates or updates the following files:

• aws-nx-plugin.config.mts records your chosen IaC provider (CDK or Terraform) and container engine; generators read iac.provider from here
• nx.json registers the sync generators (@nx/js:typescript-sync and @aws/nx-plugin:ts#sync) on the compile target so TypeScript project references stay in sync
• tsconfig.json a root TypeScript config referencing your workspace’s projects, which Nx’s TypeScript sync keeps up to date
• tsconfig.base.json the shared compiler options the plugin’s TypeScript projects extend (see below for what it carries)
• pnpm-workspace.yaml (pnpm only) allow-lists the build scripts the plugin’s dependencies need (@swc/core, esbuild, nx, sharp)
• package.json convenience scripts for common tasks, plus the nx, @nx/js, @nx/workspace, typescript and Biome dev dependencies
• biome.json default Biome formatter and linter configuration
• .mcp.json configures the MCP server for supported coding agents unless disabled (also .cursor/, .kiro/, .gemini/, .vscode/ and .codex/ equivalents)

The MCP server configuration can be disabled with --mcp=false.

Click here to see the compiler options a created tsconfig.base.json carries.

Options

Parameter	Type	Default	Description
iac	cdk | terraform	cdk	The preferred IaC provider.
mcp	boolean	true	Whether to configure the Nx Plugin for AWS MCP server for use by coding agents.
containers	infer | docker | finch	infer	The container engine to use for build/push/login. 'infer' picks docker if installed, otherwise finch (falling back to docker when neither is installed).
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Troubleshooting

The workspace is out of sync

TypeScript project references need syncing. init registers the sync generators; run:

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

ERR_PNPM_IGNORED_BUILDS during install

pnpm skips install scripts for packages that aren’t allow-listed. init allow-lists the ones the plugin’s tooling needs (@swc/core, esbuild, nx, sharp) in pnpm-workspace.yaml, but the block can fire during nx add @aws/nx-plugin itself — before init has run. Run pnpm approve-builds and approve the listed packages (or add them under allowBuilds:), then re-run the install.

nx sync hangs, or plugin worker ... exited before the connection was established

If two different nx versions are present in the same node_modules tree (run npm ls nx to confirm), their plugin-worker IPC deadlocks. The init generator pins the root nx devDependency to the version the plugin’s own @nx/* packages resolve, but a later install of another @nx/* package at a different patch version can reintroduce the mismatch. Align every nx and @nx/* entry in your root package.json to a single version and reinstall.

ts.readConfigFile is not a function

Your workspace has TypeScript 7 installed, which Nx does not yet support — Nx’s plugins rely on TypeScript’s in-process compiler API, which TypeScript 7 no longer provides. Pin typescript in your root package.json to the version the plugin uses (the init generator installs a compatible version) and reinstall.

Recursive task invocation detected

Your root package.json is registered as an Nx project (it has an "nx" key, which nx init adds for a single-package repo) and carries a build script of nx run-many --target build. Nx then infers a build target on the root that calls itself. Move your source into packages/<your-package>/ so the root becomes a workspace manifest rather than a project — see Single-package projects. (Nx’s own standalone presets avoid this by setting "nx": { "includedScripts": [] } on the root package; you can do the same as a quicker alternative.)

TypeScript errors in your existing projects after adding the plugin (TS6059, TS7016, TS5011, NG4006)

The plugin’s own generated projects carry the TypeScript settings they need in their per-project tsconfig.lib.json, so they build regardless of your tsconfig.base.json. These errors show up instead in a pre-existing project of yours that inherits a tsconfig.base.json init created (with composite/emitDeclarationOnly/nodenext) but isn’t compatible with those settings — for example, the Angular compiler rejects emitDeclarationOnly (NG4006), or a project that sets outDir without a rootDir now needs one (TS5011). Add per-project tsconfig overrides re-declaring the conflicting options for those projects (e.g. "rootDir": "src"), or point the plugin’s projects and your projects at separate base configs.

init never rewrites an existing tsconfig.base.json, precisely so it can’t silently break the projects that inherit from it — resolving these mismatches is a decision only you can make for your codebase.

ESM and CommonJS

The module format is workspace-wide, read from the root package.json type field: type: "module" means ESM, anything else (including no type field) means CommonJS. init preserves whichever your workspace uses, and the plugin’s TypeScript generators emit matching code. If you later want to switch, change the root type — but that’s a migration of your existing code, not something init does for you.