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

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

Options

Parameter	Type	Default	Description
addTsPlugin	boolean	true	Whether to add the ts plugin.
iacProvider	string	CDK	The preferred IaC provider.
gitSecrets	boolean	true	Whether to configure git-secrets to prevent committing AWS credentials.
containerEngine	string	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).

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
• aws-nx-plugin.config.mts Nx Plugin for AWS configuration
• Directory.git-secrets/ Vendored git-secrets bash script for credential scanning

  • …
• Directory.husky/ Git hooks

  • …

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 — especially in CI. 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.

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 a single node_modules containing all dependencies. If you need to add a new dependency, add it in the root package.json.

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

If you have a website, start it and all connected components locally:

pnpm

pnpm dev

yarn

yarn dev

npm

npm run dev

bun

bun dev

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 ESLint for static analysis and Prettier for code formatting. Running lint applies both to all projects.

Git Secrets

New workspaces include 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.

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
git secrets --add --allowed 'my-regex-pattern'

# Allow a literal string (special characters are escaped)
git secrets --add --allowed --literal 'my-literal+string'

You can also create a .gitallowed file at the repository root with one egrep-compatible regex per line (shared with your team via version control):

.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. Two settings are particularly useful:

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

export default {
  iac: {
    provider: 'CDK', // or 'Terraform'
  },
  containers: {
    engine: 'docker', // or 'finch'
  },
} satisfies AwsNxPluginConfig;

• iac.provider — the default infrastructure-as-code provider (CDK or Terraform) used by generators that emit infrastructure (e.g. ts#infra, ts#trpc-api, py#fast-api). Generators that accept an --iacProvider 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.

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