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

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.

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”

For maximum control, use the programmatic API to create custom release workflows:

tools/scripts/release.ts
import { releaseChangelog, releasePublish, releaseVersion } from 'nx/release';
import * as yargs from 'yargs';


(async () => {
  const options = await yargs
    .version(false) // don't use the default meaning of version in yargs
    .option('version', {
      description:
        'Explicit version specifier to use, if overriding conventional commits',
      type: 'string',
    })
    .option('dryRun', {
      alias: 'd',
      description:
        'Whether or not to perform a dry-run of the release process, defaults to true',
      type: 'boolean',
      default: true,
    })
    .option('verbose', {
      description:
        'Whether or not to enable verbose logging, defaults to false',
      type: 'boolean',
      default: false,
    })
    .parseAsync();


  const { workspaceVersion, projectsVersionData } = await releaseVersion({
    specifier: options.version,
    dryRun: options.dryRun,
    verbose: options.verbose,
  });


  await releaseChangelog({
    versionData: projectsVersionData,
    version: workspaceVersion,
    dryRun: options.dryRun,
    verbose: options.verbose,
  });


  // publishResults contains a map of project names and their exit codes
  const publishResults = await releasePublish({
    dryRun: options.dryRun,
    verbose: options.verbose,
    // You can optionally pass through the version data (e.g. if you are using a custom publish executor that needs to be aware of versions)
    // It will then be provided to the publish executor options as `nxReleaseVersionData`
    // This is not required for the default @nx/js publish executor
    versionData: projectsVersionData,
  });


  process.exit(
    Object.values(publishResults).every((result) => result.code === 0) ? 0 : 1
  );
})();

Learn More

Section titled “Learn More”

Configuration & Customization

Section titled “Configuration & Customization”

Workflows

Section titled “Workflows”

References

Section titled “References”