Docker Bundling

Several generators (such as ts#agent and py#agent) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a FastAPI project on Amazon ECS, or deploying a containerised Express server.

Docker or Finch

The container engine used to build images is chosen at workspace creation time via the --containers flag (docker, finch, or infer — the default — which auto-detects what’s installed). Finch is an open-source, drop-in alternative to Docker. The selection is recorded in aws-nx-plugin.config.mts and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the CDK_DOCKER environment variable.

The Pattern

The recommended pattern has three pieces:

1. A bundle target on your project which produces a self-contained directory of runtime artifacts. For TypeScript this is a tree-shaken, single-file JavaScript bundle produced by Rolldown; for Python this is a requirements.txt and installed dependencies produced by uv.
2. A minimal Dockerfile which simply COPYs the bundle output into a base image. Because bundling already handled tree-shaking and dependency installation, the Dockerfile does not need to run npm install or uv sync.
3. A docker target which copies the Dockerfile alongside the bundle output (so that the Docker build context only contains files needed at runtime), then runs docker build.

The Docker build context is written to your project’s dist folder. Your infrastructure as code (CDK or Terraform) then points at that directory to push the image to ECR.

Why bundle outside the Dockerfile?

Keeping the bundle step in Nx (rather than inside the Dockerfile) means:

• Nx can cache the bundle target — its output is a directory on disk, so a cache hit genuinely restores it.
• The Dockerfile does not need access to your monorepo, private registries, or build-time secrets.
• The image layer is tiny — a single COPY of already-built artifacts, with no transitive node_modules or build toolchain.

TypeScript

Bundle Target

Configure a bundle target that invokes Rolldown. If you are starting from a ts#project, add the following to your project.json:

{
  "targets": {
    "bundle": {
      "cache": true,
      "inputs": ["default"],
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle"],
      "options": {
        "command": "rolldown -c rolldown.config.ts",
        "cwd": "{projectRoot}"
      },
      "dependsOn": ["compile"]
    }
  }
}

And a rolldown.config.ts at the root of your project:

rolldown.config.ts

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    tsconfig: 'tsconfig.lib.json',
    input: 'src/index.ts',
    output: {
      file: '../../dist/packages/my-project/bundle/index.js',
      format: 'cjs',
      codeSplitting: false,
    },
    platform: 'node',
  },
]);

Run the bundle target to produce dist/packages/my-project/bundle/index.js:

pnpm

pnpm nx bundle my-project

yarn

yarn nx bundle my-project

npm

npx nx bundle my-project

bun

bunx nx bundle my-project

Non-bundleable dependencies

Some npm packages cannot be bundled because they rely on dynamic require, native bindings, or runtime file-path resolution. Add them to the external array in rolldown.config.ts so they are left as runtime require() calls, and install them inside the Dockerfile instead (see below):

{
  // ...
  external: ['@aws/aws-distro-opentelemetry-node-autoinstrumentation'],
}

Dockerfile

Create a Dockerfile in your project source directory. The file does nothing more than apply the base image’s security updates, COPY the bundle into a Node base image, plus npm install any external packages that could not be bundled. Place the RUN npm install step before the COPY, so Docker can cache the installed node_modules layer and only re-run it when the dependency list actually changes:

FROM public.ecr.aws/docker/library/node:lts

# Apply the distribution's security updates: base image tags lag behind the
# security suite, so their OS packages carry vulnerabilities that already have a
# published fix.
RUN apt-get update && \
    apt-get upgrade -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Install packages that cannot be bundled (declared as "external" in rolldown.config.ts).
# Kept above the COPY so this layer is cached and only invalidated when the install list changes.
RUN npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation@0.10.0

# Copy bundled application
COPY index.js /app

EXPOSE 8080

CMD ["node", "index.js"]

Pin your dependencies

Pin every dependency installed inside the Dockerfile to an exact version (as above) — otherwise npm install will silently pick up a newer release the next time you build, producing images that behave differently depending on when they were built.

Docker Target

Add a docker target which:

1. Copies the Dockerfile into the bundle output directory (so the build context contains only the bundle + Dockerfile), and
2. Runs docker build (optional for CDK — see below).

{
  "targets": {
    "docker": {
      "cache": false,
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "shx cp packages/my-project/src/Dockerfile dist/packages/my-project/bundle/Dockerfile",
          "docker build --platform linux/arm64 -t my-scope-my-project:latest dist/packages/my-project/bundle"
        ],
        "parallel": false
      },
      "dependsOn": ["bundle"]
    }
  }
}

Do not cache image builds

Set "cache": false on image build targets. A built image is not written to an outputs path in the filesystem, so Nx has nothing to restore on a cache hit. Container engines cache image layers regardless, so there is no performance penalty.

Cross-platform file copy

The shx package provides cross-platform cp, rm and mkdir commands, avoiding the shell builtins (unavailable on Windows). Install it at the root of your workspace:

pnpm

pnpm add -Dw shx

yarn

yarn add -D shx

npm

npm install --legacy-peer-deps -D shx

bun

bun add -D shx

Running this target produces a local image tagged my-scope-my-project:latest, built from the minimal context at dist/packages/my-project/bundle/:

pnpm

pnpm nx docker my-project

yarn

yarn nx docker my-project

npm

npx nx docker my-project

bun

bunx nx docker my-project

CDK builds the image itself

If you are only deploying with CDK, the docker build command above is optional — CDK’s DockerImageAsset (shown under Infrastructure) will build the image for you at synth time. You still need to copy the Dockerfile into the build-context directory so CDK can find it. The generators keep the local docker build step to give you a quick way to smoke-test the image with docker run.

For Terraform, the docker build step is required — the null_resource pattern below pushes a locally-tagged image.

Python

Bundle Target

Configure a bundle target that uses uv to export and install dependencies for your target platform. The py#project generator and the py#lambda-function generator both configure this for you. The target configuration looks like:

{
  "targets": {
    "bundle-arm": {
      "cache": true,
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-arm"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_project -o dist/{projectRoot}/bundle-arm/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform aarch64-manylinux_2_28 --target dist/{projectRoot}/bundle-arm -r dist/{projectRoot}/bundle-arm/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    }
  }
}

Target architecture

Change --python-platform to x86_64-manylinux_2_28 if your Docker image will run on x86_64.

Running nx bundle my-project produces dist/packages/my-project/bundle-arm/ containing your project’s source, its dependencies, and a requirements.txt — everything the image needs at runtime.

Dockerfile

The Dockerfile applies the base image’s security updates, then copies the bundle into a Python base image. Because uv already installed all dependencies into the bundle directory, you do not need to run pip install inside the image:

FROM public.ecr.aws/docker/library/python:3.14-slim

# Apply the distribution's security updates: base image tags lag behind the
# security suite, so their OS packages carry vulnerabilities that already have a
# published fix.
RUN apt-get update && \
    apt-get upgrade -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy bundled package (source + installed dependencies)
COPY . /app

EXPOSE 8080

ENV PYTHONPATH=/app
ENV PATH="/app/bin:${PATH}"

CMD ["python", "-m", "my_project.main"]

Docker Target

Add a docker target which copies the Dockerfile into the bundle output directory, then runs docker build:

{
  "targets": {
    "docker": {
      "cache": false,
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "shx rm -rf dist/packages/my-project/docker",
          "shx mkdir -p dist/packages/my-project/docker",
          "shx cp -R dist/packages/my-project/bundle-arm/. dist/packages/my-project/docker",
          "shx cp packages/my-project/src/Dockerfile dist/packages/my-project/docker/Dockerfile",
          "docker build --platform linux/arm64 -t my-scope-my-project:latest dist/packages/my-project/docker"
        ],
        "parallel": false
      },
      "dependsOn": ["bundle-arm"]
    }
  }
}

This clears the output directory, then copies both the bundle contents and the Dockerfile into dist/.../docker, which becomes the Docker build context.

pnpm

pnpm nx docker my-project

yarn

yarn nx docker my-project

npm

npx nx docker my-project

bun

bunx nx docker my-project

Scanning Images with Trivy

It’s good practice to scan your images for known vulnerabilities. The generators that follow this pattern add a trivy target which scans the built image with Trivy, running from the ECR-hosted Trivy image, and exits non-zero on HIGH or CRITICAL findings.

The target copies a .trivyignore from the root of your project into the scan directory and passes it to Trivy with --ignorefile, so create that file first — an empty one is fine, and it is where you suppress findings later:

touch packages/my-project/.trivyignore

Then add a trivy target which dependsOn your docker target. It saves the built image to a tarball and scans it via a workspace-relative bind mount, so the same command works under both docker and finch:

{
  "targets": {
    "trivy": {
      "cache": false,
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/trivy"],
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "shx rm -rf dist/packages/my-project/trivy",
          "shx mkdir -p dist/packages/my-project/trivy",
          "shx cp packages/my-project/.trivyignore dist/packages/my-project/trivy/.trivyignore",
          "docker save -o dist/packages/my-project/trivy/image.tar my-scope-my-project:latest",
          "docker run --rm -v \"./dist/packages/my-project/trivy\":/scan public.ecr.aws/aquasecurity/trivy:0.72.0 image --input /scan/image.tar --ignorefile /scan/.trivyignore --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 --no-progress -q"
        ],
        "parallel": false
      },
      "dependsOn": ["docker"]
    }
  }
}

Each project’s per-image scan targets are aggregated under a workspace-wide trivy target, which the vended trivy root script runs (nx run-many --target trivy).

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

Run Trivy in CI

The scan is intentionally not wired into build since this can introduce unnecessary friction when iterating during development, as Trivy’s vulnerabilty database is continually updated with new CVEs.

Instead we recommend running the above command as a dedicated step in your CI pipeline prior to deployment to production stages.

Suppressing findings

Trivy reads a .trivyignore file (a list of vulnerability IDs, one per line) from the root of your project. --ignore-unfixed skips vulnerabilities with no available fix, so the scan only fails on issues you can action by upgrading tooling in your Dockerfile. See the Trivy filtering documentation for details.

Apply the distribution’s security updates

A base image tag lags behind its distribution’s security suite, so its OS packages carry vulnerabilities that already have a published fix. Upgrade them as the first step of your build, ahead of any other instruction so later layers install against the upgraded packages. For a Debian-derived base image (as used by the Node and Python images above):

RUN apt-get update && \
    apt-get upgrade -y --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

The generated Dockerfiles do this for you.

Infrastructure

Wiring the resulting build-context directory to infrastructure as code is the same for both TypeScript and Python — only the path to the build-context directory differs (dist/packages/my-project/bundle for TypeScript, dist/packages/my-project/docker for Python).

CDK

Use CDK’s DockerImageAsset pointed at the build-context directory. CDK will build the image and publish it to the CDK asset ECR repository at deploy time:

import { DockerImageAsset, Platform } from 'aws-cdk-lib/aws-ecr-assets';
import { findWorkspaceRoot } from '@my-scope/common-constructs';
import * as path from 'path';
import * as url from 'url';

const image = new DockerImageAsset(this, 'MyImage', {
  directory: path.join(
    // Resolve from the compiled construct location to the workspace root
    findWorkspaceRoot(url.fileURLToPath(new URL(import.meta.url))),
    'dist/packages/my-project/bundle',
  ),
  platform: Platform.LINUX_ARM64,
});

The findWorkspaceRoot helper is generated by the ts#infra generator and exported from @my-scope/common-constructs. If you are not using shared constructs, you can hardcode the path to the dist directory relative to where cdk is invoked from — typically the workspace root — and omit the findWorkspaceRoot call entirely.

Running bundle before synth

CDK does not run the bundle/docker targets automatically — you must run nx build my-project (or wire the deploy target to depend on build) before cdk deploy. The generators that use this pattern declare docker and bundle as dependencies of build so this happens transparently.

Use the DockerImageAsset with any AWS construct that accepts a container image, for example aws_ecs.ContainerImage.fromDockerImageAsset(image).

Terraform

Terraform’s AWS provider does not have a first-class “build and push a Docker image” resource. The pattern used by the generators is:

1. The project’s build target runs docker build, producing a local image tagged my-scope-my-project:latest.
2. A shared ECR repository using the core/asset-ecr module
3. A null_resource with a local-exec provisioner that authenticates to ECR, re-tags the locally-built image with its content digest, and pushes it.
4. The downstream resource (e.g. aws_ecs_task_definition) references the image by its immutable, digest-based tag.

Because one repository holds every image, each tag is namespaced by the image’s owner as well as its digest, so images sharing the registry never collide.

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

# Invalidate the push whenever the locally-built image digest changes
data "external" "docker_digest" {
  program = ["sh", "-c", "echo '{\"digest\":\"'$(docker inspect my-scope-my-project:latest --format '{{.Id}}')'\"}'"]
}

locals {
  # Content-based, immutable image tag derived from the local image digest, and
  # namespaced by owner so images sharing the registry never collide
  image_tag = "my-project-${replace(data.external.docker_digest.result.digest, "sha256:", "")}"
}

resource "null_resource" "docker_publish" {
  triggers = {
    docker_digest  = data.external.docker_digest.result.digest
    repository_url = module.asset_ecr.repository_url
    image_tag      = local.image_tag
  }

  provisioner "local-exec" {
    command = <<-EOT
      aws ecr get-login-password --region ${data.aws_region.current.id} \
        | docker login --username AWS --password-stdin ${self.triggers.repository_url}
      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:${self.triggers.image_tag}
      docker push ${self.triggers.repository_url}:${self.triggers.image_tag}
    EOT
  }
}

The data.external.docker_digest block ensures the null_resource re-runs whenever the local image hash changes, triggering a new push on every meaningful code change. The image is pushed under an immutable, content-based tag derived from its digest, so the shared repository uses IMMUTABLE tag mutability and rejects any attempt to overwrite an existing tag.

Running bundle before apply

nx apply <project> requires the image tag my-scope-my-project:latest to already exist locally. Run nx build my-project (or nx docker my-project) before nx apply <project>.

Further Reading

• ts#agent generator — a complete example of this pattern for a TypeScript agent deployed to Bedrock AgentCore Runtime.
• py#agent generator — the equivalent for Python.
• Rolldown documentation — configuration reference for the TypeScript bundler.
• uv documentation — reference for Python dependency export and install.