Release Management

Use nx release to version projects, generate changelogs from commits, and publish to npm or other registries — with support for independent versioning and release groups.

nx release is a set of tools for managing the full release lifecycle of your libraries and applications: versioning, changelog generation, and publishing.

Publishing is difficult to undo. Always start with --dry-run to preview what will happen before committing to a release.

nx release --dry-run

What makes up a release?

A release consists of three phases that can be run together or independently:

1. Versioning

   Determine the next version for each project and update any projects that depend on them. Versions follow semantic versioning (semver) by default.

   nx release version
   # or with an explicit specifier:
   nx release version minor
   
2. Changelog generation

   Derive a changelog from commit messages or version plan files and write it to CHANGELOG.md.

   nx release changelog 1.2.0
   
3. Publishing

   Publish packages to a registry (e.g. npm, crates.io, a Docker registry).

   nx release publish
   

Run the full release

The top-level nx release command runs all three phases in order:

# Preview the full release without writing anything
nx release --dry-run

# First release (no prior git tags to compare against)
nx release --first-release --dry-run

# Release with an explicit version specifier
nx release minor

When you run nx release without a specifier, Nx prompts you to choose a semver keyword (major, minor, patch) or enter a custom version.

Configure nx release

Configure Nx Release in nx.json under the release key:

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

Configure versioning

// nx.json
{
  "release": {
    "version": {
      "conventionalCommits": true
    }
  }
}

When conventionalCommits is enabled, Nx determines the version bump automatically based on commit message prefixes (feat:, fix:, chore:, etc.).

Configure changelog

// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "createRelease": "github"
      },
      "projectChangelogs": true
    }
  }
}

Configure git operations

# Commit, tag, and push as part of versioning
nx release version --git-commit --git-tag --git-push

Or configure defaults in nx.json:

// nx.json
{
  "release": {
    "git": {
      "commit": true,
      "tag": true,
      "push": true
    }
  }
}

Release groups for independent versioning

Release groups let you version subsets of projects independently with different configuration:

// nx.json
{
  "release": {
    "groups": {
      "npm-packages": {
        "projects": ["packages/*"],
        "version": {
          "conventionalCommits": true
        },
        "changelog": {
          "createRelease": "github"
        }
      },
      "internal-tools": {
        "projects": ["tools/*"],
        "version": {
          "specifierSource": "prompt"
        }
      }
    }
  }
}

Target a specific group when running release commands:

nx release --groups=npm-packages
nx release version --groups=npm-packages minor

Publish options

# Publish to a specific registry
nx release publish --registry=https://my-registry.example.com

# Publish with a specific dist tag
nx release publish --tag=next

# Publish with a one-time password (2FA)
nx release publish --otp=123456

# Set access level for scoped packages
nx release publish --access=public

Programmatic API

For complex or highly customized release workflows, use the programmatic API directly in a Node.js script:

import { releaseVersion, releaseChangelog, releasePublish } from 'nx/release';

async function main() {
  const { workspaceVersion, projectsVersionData } = await releaseVersion({
    specifier: 'minor',
    dryRun: false,
  });

  await releaseChangelog({
    versionData: projectsVersionData,
    version: workspaceVersion,
    dryRun: false,
  });

  const publishStatus = await releasePublish({
    dryRun: false,
  });

  process.exit(publishStatus);
}

main();

This is especially useful when the CLI’s prompts or built-in logic don’t cover your team’s specific release requirements.

Version plans (file-based versioning)

Instead of deriving version bumps from commit messages, you can create explicit version plan files:

# Create a version plan interactively
nx release plan

# Create a version plan with a specific bump
nx release plan minor --message="Add new authentication API"

Version plan files are committed alongside your code changes and consumed during the next release.

Verify that all touched projects have a version plan:

nx release plan:check

nx release CLI reference

Full reference for all nx release subcommands and flags.

nx.json release configuration

Configure release groups, versioning strategy, and changelog in nx.json.

CI setup

Set up automated releases in GitHub Actions, GitLab, or other CI providers.

Extend Nx

Write custom generators and executors to customize your release workflow.