Workspace

When you create a new workspace with @aws/nx-plugin, the preset generator sets up an Nx monorepo with sensible defaults for building on AWS.

Creating a Workspace

Create your workspace@aws/nx-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

Build your command8

workspaceRequired

iac

cdkterraform

containers

inferdockerfinch

gitSecrets

true

mcp

true

module

esmcjs

catalog

true

preferInstallDependencies

true

Options

Generator Options7 options

iacenumDefault: cdk

The preferred IaC provider.

cdkterraform

containersenumDefault: 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).

inferdockerfinch

gitSecretsbooleanDefault: true

Whether to configure git-secrets to prevent committing AWS credentials.

mcpbooleanDefault: true

Whether to configure the Nx Plugin for AWS MCP server for use by coding agents.

moduleenumDefault: esm

Module format for generated TypeScript code and configuration.

esmcjs

catalogbooleanDefault: true

Whether generators record dependency versions in the package manager's catalog (pnpm/yarn/bun), keeping a single source of truth for versions. When false, dependencies are written directly to each project's package.json and keeping versions aligned is your responsibility.

preferInstallDependenciesbooleanDefault: 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.

Workspace Structure

• Directorypackages/ 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
• Directory.git-secrets/ Vendored git-secrets bash script for credential scanning

  • …
• .gitallowed Patterns git-secrets treats as false positives
• Directory.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 is a language-agnostic build system for monorepos, managing dependencies between projects written in any programming language and the tasks to build them. You can learn more on the Nx website.

Projects

An Nx monorepo is made up of one or more projects, each with a project.json file. The project.json defines a project’s tasks, known as targets, which define how a project is built, run locally, tested, etc. It also defines dependencies between targets within or across projects.

For example, a project.json might define a build target that depends on all upstream projects being built first:

packages/my-project/project.json

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

Tip

For projects in languages not directly supported by the Nx Plugin for AWS, you can often find a generator in the Nx Plugin Registry to help. It’s simple to add a project of any language into your monorepo however — just add a project.json file and define its build target to run the specific build command for a project of that language.

For details on how TypeScript and Python projects are set up, refer to the ts#project and py#project generator guides.

Caching

Nx caches the output of previously executed targets and replays them when the inputs haven’t changed. This dramatically speeds up builds, tests, and linting. If you encounter stale or unexpected behaviour, reset the cache with:

pnpm

pnpm nx reset

yarn

yarn nx reset

npm

npx nx reset

bun

bunx nx reset

For more details, see the Nx caching documentation.

Parallelism

New workspaces set parallel in nx.json, which controls how many tasks Nx runs concurrently:

nx.json

{
  "parallel": 8
}

Lower it if you’re building on a machine with fewer cores or limited memory. You can also override it per-invocation:

pnpm

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

yarn

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

npm

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

bun

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

Single Version Policy

The default monorepo setup uses a single version policy for both Node and Python based projects.

This means that all projects within your monorepo use the same version of dependencies by default, reducing issues related to packages in the same monorepo running into version mismatch issues.

From a Node perspective this means a single lockfile at the root, with dependencies installed once and linked into each project. Each Node project declares the runtime dependencies its source imports in its own package.json, while shared build/test tooling lives in the root package.json devDependencies. Add a project’s runtime dependency by installing it into that 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

For package managers with catalog support (pnpm, yarn and bun), dependency versions are recorded in the catalog and referenced with the catalog: protocol, keeping a single source of truth for versions across every project’s package.json. For npm workspaces, we recommend syncpack to align versions declared across multiple package.json files.

From a Python perspective, this means a single .venv in the root of the monorepo with all dependencies installed into it. Each Python project has its own pyproject.toml, but the versions of those dependencies are managed by the UV workspace and subsequently written out to the uv.lock file in the root.

Common Commands

Build

Build all projects in the workspace:

pnpm

pnpm build

yarn

yarn build

npm

npm run build

bun

bun build

Lint

Lint and auto-fix all projects:

pnpm

pnpm lint

yarn

yarn lint

npm

npm run lint

bun

bun lint

Test

Run tests across all projects:

pnpm

pnpm test

yarn

yarn test

npm

npm run test

bun

bun test

Dev

Start all local development servers across your workspace:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

See the Local Development guide for more details.

Sync

Run any sync generators, which for example synchronise TypeScript project references (refer to the ts#project generator guide for more details):

pnpm

pnpm nx sync

yarn

yarn nx sync

npm

npx nx sync

bun

bunx nx sync

Run Specific Targets

You can run specific targets for specific projects with:

pnpm

pnpm nx <target> <project>

yarn

yarn nx <target> <project>

npm

npx nx <target> <project>

bun

bunx nx <target> <project>

For example:

pnpm

pnpm nx build website

yarn

yarn nx build website

npm

npx nx build website

bun

bunx nx build website

This will run the chosen target as well as the targets it depends on.

What’s Included

Linting

New workspaces are configured with Biome for static analysis and code formatting. Running lint checks all projects for issues, and lint --configuration=fix auto-fixes them.

MCP Configuration

The plugin’s MCP server is configured as a project level MCP server for Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot and OpenAI Codex, so your coding assistant can discover and run the plugin’s generators without any setup. The configuration is committed with your workspace, giving everyone on your team the same setup. Remove any configurations for coding assistants you and your team do not use.

Git Secrets

Workspaces are set up with git-secrets pre-commit hooks that scan staged files for AWS credential patterns before each commit. This prevents accidentally committing access keys, secret keys, and other sensitive values.

The script is vendored into the workspace at .git-secrets/git-secrets and run by the .husky/pre-commit hook, so there is nothing to install — but it is not on your PATH, so invoke it by path rather than as git secrets.

Suppressing False Positives

Patterns in git-secrets use egrep-compatible regular expressions. If git-secrets blocks a commit that does not contain real credentials:

# 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

These are recorded in your local git config, so they apply only to your own clone. To share a suppression with your team, add it to the .gitallowed file at the repository root instead — one egrep-compatible regex per line, matched against <path>:<line-number>:<line-contents>:

.gitallowed

# Allow test fixtures
tests/fixtures/.*
# Allow a specific string
EXAMPLE[A-Z]{16}

For full details on managing patterns, see the git-secrets documentation.

Nx Plugin for AWS Configuration

The workspace ships with an aws-nx-plugin.config.mts file at the root. Generators read this file to pick sensible defaults so you don’t have to pass the same flags every time:

// 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 — the default infrastructure-as-code provider (cdk or terraform) used by generators that emit infrastructure (e.g. ts#infra, ts#api, py#api). Generators that accept an --iac flag default to inherit, which reads this value.
• containers.engine — the container CLI (docker or finch) baked into generated build/push/login commands. CDK image-asset builds also pick this up via the CDK_DOCKER environment variable. See the Docker bundling guide for details.
• packageManager.catalogs — whether generators record dependency versions in the package manager’s catalog and reference them with the catalog: protocol (see Single Version Policy). Set it to false to have generators write direct version ranges into each project’s package.json instead. It has no effect on npm, which has no catalog.

The license generator adds a license key to this same file to configure its own behaviour.

You can edit any setting at any time — subsequent generator runs will pick up the new value.