Overview of the Nx Docker Plugin

The Nx Plugin for Docker contains executors and utilities for building and publishing docker images within an Nx workspace. Using the @nx/docker Inference Plugin, Nx will automatically detect Dockerfile's in your workspace and provide a docker:build and docker:run target for each. It will also provide a nx-release-publish target for publishing docker images to a registry.

Installation

In any Nx workspace, you can install @nx/docker by running the following command:

nx add @nx/docker

This will install the correct version of @nx/docker to match the version of Nx you are using.

Minimum Nx Version

The @nx/docker plugin only became available in Nx 21.4.0-beta.9. Your Nx Workspace will need to be on this version or higher to use it.

How @nx/docker Infers Tasks

The @nx/docker plugin will create a task for any project that has a Dockerfile present. It will infer the following tasks:

• docker:build
• docker:run
• nx-release-publish

View Inferred Tasks

To view inferred tasks for a project, open the project details view in Nx Console or run nx show project my-project in the command line.

@nx/docker Configuration

The @nx/docker plugin is configured in the plugins array in nx.json.

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": "docker:build",
        "runTarget": "docker:run"
      }
    }
  ]
}

The buildTarget and runTarget options control the names of the inferred Docker tasks. The default names are docker:build and docker:run.

Advanced Plugin Configuration

The buildTarget and runTarget options can be configured as objects to provide additional customization beyond just naming the targets. This allows you to pass custom arguments, set environment variables, and use pattern interpolation.

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": {
          "name": "docker:build",
          "args": [
            "--platform",
            "linux/amd64,linux/arm64",
            "--label",
            "project={projectName}"
          ],
          "env": {
            "DOCKER_BUILDKIT": "1"
          },
          "envFile": ".env.docker",
          "cwd": "{projectRoot}/docker"
        },
        "runTarget": {
          "name": "docker:run",
          "args": ["--rm"],
          "env": {
            "NODE_ENV": "production"
          }
        }
      }
    }
  ]
}

Configuration Properties

When using the object format, the following properties are available:

• name (string, required): The name of the inferred target
• args (string[], optional): Additional arguments to pass to the Docker command. Supports pattern interpolation.
• env (object, optional): Environment variables to set when running the Docker command. Values support pattern interpolation.
• envFile (string, optional): Path to an environment file to load
• cwd (string, optional): Working directory for the command. Supports pattern interpolation.

Pattern Interpolation

All string values in the configuration support pattern interpolation using the following tokens:

• {projectName} - The name of the project from project.json or package.json
• {projectRoot} - The root directory of the project (e.g., apps/api)
• {imageRef} - The default image reference derived from the project root (e.g., apps-api)
• {currentDate} - Current date in ISO format (e.g., 2025-01-30T14:30:00.000Z)
• {currentDate|FORMAT} - Current date with custom formatting (e.g., {currentDate|YYYY.MM.DD} → 2025.01.30)
• {commitSha} - Full Git commit SHA
• {shortCommitSha} - First 7 characters of the commit SHA
• {env.VAR_NAME} - Environment variable values (e.g., {env.BUILD_NUMBER})

Date formatting supports these tokens: YYYY (year), YY (2-digit year), MM (month), DD (day), HH (hours), mm (minutes), ss (seconds).

Example: Multi-Platform Build with Metadata

Here's a practical example that builds Docker images for multiple platforms and includes build metadata:

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/docker",
      "options": {
        "buildTarget": {
          "name": "build",
          "args": [
            "--platform",
            "linux/amd64,linux/arm64",
            "--label",
            "org.opencontainers.image.title={projectName}",
            "--label",
            "org.opencontainers.image.source={projectRoot}",
            "--label",
            "org.opencontainers.image.revision={commitSha}",
            "--label",
            "org.opencontainers.image.created={currentDate}",
            "--build-arg",
            "BUILD_DATE={currentDate|YYYY-MM-DD}",
            "--build-arg",
            "VERSION={env.VERSION}",
            "--tag",
            "{imageRef}:{currentDate|YYMMDD}.{shortCommitSha}"
          ],
          "env": {
            "DOCKER_BUILDKIT": "1",
            "IMAGE_NAME": "{imageRef}"
          }
        },
        "runTarget": {
          "name": "run",
          "args": [
            "--rm",
            "--publish",
            "3000:3000",
            "--env",
            "NODE_ENV=production"
          ]
        }
      }
    }
  ]
}

This configuration:

• Builds for both AMD64 and ARM64 architectures
• Adds OpenContainers metadata labels with project information
• Tags images with a calendar version and commit SHA (e.g., my-app:250130.abc1234)
• Enables Docker BuildKit for improved build performance
• Injects build arguments and environment variables from the CI/CD pipeline

Using Nx Release to Publish Docker Images

The @nx/docker plugin provides a nx-release-publish target for publishing docker images to a registry. Nx Release was also updated to support versioning docker images, generating changelogs, and publishing docker images to a registry through a single command.

You can learn more about how to manage releases for Docker Images in the Release Docker Images guide.