README.md

February 11, 2026 · View on GitHub

The @nx-tools/nx-container plugin streamlines container image workflows in Nx monorepos by providing a unified interface for multiple container build engines and automated image management capabilities.

Key Features

Multi-Engine Support: Build container images using your preferred container engine:
- Docker Buildx with Moby BuildKit for advanced build features
- Podman for rootless and daemonless container builds
Automated Image Management: Intelligent tag generation and OCI Image Format Specification compliant labeling
Project Scaffolding: Code generators to quickly configure container builds for your applications

Getting Started

Installation

To add the @nx-tools/nx-container plugin to your Nx workspace, run the following command:

npx nx add @nx-tools/nx-container

This command will:

Install the plugin package
Configure the plugin in your nx.json file
Set up default configurations for your workspace

Task Inference

The plugin automatically detects projects suitable for containerization and adds a container task to any project containing a Dockerfile. This intelligent inference eliminates the need for manual task configuration in most cases.

Viewing Inferred Tasks

To inspect the automatically inferred tasks for any project:

Using Nx Console: Open the project details view for comprehensive task visualization
Using CLI: Execute nx show project <project-name> to display project configuration and available tasks

Configuration

Plugin Configuration

Configure the @nx-tools/nx-container plugin in your workspace's nx.json file within the plugins array:

{
  "plugins": [
    {
      "plugin": "@nx-tools/nx-container",
      "options": {
        "defaultEngine": "docker",
        "defaultRegistry": "docker.io"
      }
    }
  ]
}

Alternative Engine Configuration

You can customize the default build engine and registry to match your infrastructure requirements:

{
  "plugins": [
    {
      "plugin": "@nx-tools/nx-container",
      "options": {
        "defaultEngine": "podman",
        "defaultRegistry": "ghcr.io"
      }
    }
  ]
}

Supported Engines:

docker (default) - Standard Docker builds with BuildKit
podman - Rootless container builds

Common Registries:

docker.io - Docker Hub (default)
ghcr.io - GitHub Container Registry
gcr.io - Google Container Registry
Custom registry URLs

Build your application

nx container appName

To use a different engine, you need to update the options.engine property of your project target or use the INPUT_ENGINE environment variable. All possible values are docker (the default) and podman

Important

You can set docker or podman engine in your project.json targets to use in your dev machine, and use INPUT_ENGINE env variable to use docker in your CI/CD pipelines.

Package reference

Here is a list of all the executors and generators available from this package:

Executors

build: Builds an image using instructions from the Dockerfile and a specified build context directory.

Generators

init: Initialize Container settings for your workspace.
configuation: Configure Container builds for your application.

Community

Join the growing Nx Tools community! We believe in building together and welcome contributors of all experience levels.

Get Involved

Report Issues: Found a bug or have a suggestion? Open an issue on GitHub
Ask Questions: Need help or clarification? Start a conversation in GitHub Discussions
Contribute Code: Pull requests are welcome! Check our contribution guidelines to get started
Share Your Work: Built something with Nx Tools? Share it with the community in the Showcase discussion
Spread the Word: Star the repository, share on social media, or write about your experience

Resources

GitHub Repository - Source code, issues, and project management
GitHub Discussions - Community conversations and support
NPM Package - Latest releases and installation information
Documentation - Comprehensive guides and API reference
Code of Conduct - Our community standards and expectations

Your feedback and contributions help make Nx Tools better for everyone!