@nx-tools/nx-container

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.

More Documentation

• Advanced usage:

  • Multi-platform image
  • Push to multi-registries
  • Cache
  • Local registry
  • Export image to Docker
  • Handle tags and labels

• Usage with CI

  • GitLab CI
  • GitHub Actions

• Frequently Asked Questions

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!

Sponsors

License

MIT License © Gustavo Perdomo