Skip to content
Nx Docs

Manage Releases

Once you have leveraged Nx's powerful code generation and task running capabilities to build your libraries and applications, you will want to share them with your users.

Free Course: Versioning and Releasing NPM packages with Nx

Nx provides a set of tools to help you manage your releases called nx release.

We recommend always starting with --dry-run, because publishing is difficult to undo

Terminal window
nx release --dry-run

What makes up a release?

Section titled “What makes up a release?”

A release can be thought about in three main phases:

  1. Versioning - The process of determining the next version of your projects, and updating any projects that depend on them to use the new version.
  2. Changelog - The process of deriving a changelog from your commit messages or version plan files, which can be used to communicate the changes to your users.
  3. Publishing - The process of publishing your projects to a registry, such as npm for TypeScript/JavaScript libraries, crates.io for Rust, or Docker registries for container images.

Running Releases

Section titled “Running Releases”

The nx release command is used to run the release process from end to end. It is a wrapper around the three main phases of a release to provide maximum convenience and ease of use.

By default, when you run nx release it will prompt you for a version keyword (e.g. major, minor, patch) or a custom version number. The release command will then run the three phases of the release process in order: versioning, changelog generation, and publishing.

When trying it out for the first time, you need to pass the --first-release flag since there is no previous release to compare against for changelog purposes. It is strongly recommended to use the --dry-run flag to see what will be published in the first release without actually pushing anything to the registry.

Terminal window
nx release --first-release --dry-run

Set Up Your Workspace

Section titled “Set Up Your Workspace”

Follow our guides to set up Nx Release for your workspace.

TypeScript/JavaScript to NPM Publish TypeScript and JavaScript packages to NPM or private registries with semantic versioning.
Docker Images Version and publish Docker images with calendar-based versioning for continuous deployment.
Rust Crates Publish Rust packages to crates.io with cargo integration.

Basic Configuration

Section titled “Basic Configuration”

Configure Nx Release in your nx.json file:

nx.json
{
  "release": {
    "projects": ["packages/*"]
  }
}

The nx release command is customizable. You can customize the versioning, changelog, and publishing phases of the release process independently through a mixture of configuration and CLI arguments.

See the configuration reference for all available options.

Using the Programmatic API for Nx Release

Section titled “Using the Programmatic API for Nx Release”

A powerful feature of Nx Release is the fact that it is designed to be used via a Node.js programmatic API in addition to the nx release CLI.

Releases are a hugely complex and nuanced process, filled with many special cases and idiosyncratic preferences, and it is impossible for a CLI to be able to support all of them out of the box. By having a first-class programmatic API, you can go beyond the CLI and create custom release workflows that are highly dynamic and tailored to your specific needs.

See our dedicated guide on the programmatic API to learn more and see some example release scripts.

Learn More

Section titled “Learn More”

Configuration & Customization

Section titled “Configuration & Customization”

Workflows

Section titled “Workflows”

References

Section titled “References”