---
title: 'Manage Releases'
description: 'Learn how to use Nx release tools to version, generate changelogs, and publish your projects with confidence using conventional commits.'
sidebar:
  order: 9
filter: 'type:Features'
---

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

{% linkcard title="Free Course: Versioning and Releasing NPM packages with Nx" href="https://www.epicweb.dev/tutorials/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

```shell
nx release --dry-run
```

## 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](/docs/guides/nx-release/file-based-versioning-version-plans) 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

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.

```shell
nx release --first-release --dry-run
```

{% aside type="tip" title="Semantic Versioning" %}
By default, the version follows semantic versioning (semver) rules. To disable this behavior, set `release.releaseTag.requireSemver` to `false` in your `nx.json` file. This allows you to use custom versioning schemes.
{% /aside %}

## Set up your workspace

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

{% cardgrid %}

{% linkcard title="TypeScript/JavaScript to NPM" description="Publish TypeScript and JavaScript packages to NPM or private registries with semantic versioning." href="/docs/guides/nx-release/release-npm-packages" /%}

{% linkcard title="Docker Images" description="Version and publish Docker images with calendar-based versioning for continuous deployment."  href="/docs/guides/nx-release/release-docker-images" /%}

{% linkcard title="Rust Crates" description="Publish Rust packages to crates.io with cargo integration." href="/docs/guides/nx-release/publish-rust-crates" /%}

{% /cardgrid %}

## Basic configuration

Configure Nx Release in your `nx.json` file:

```jsonc
// 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](/docs/reference/nx-json#release) for all available options.

## 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](/docs/guides/nx-release/programmatic-api) to learn more and see some example release scripts.

## Learn more

### Configuration & customization

- **[Version Projects Independently](/docs/guides/nx-release/release-projects-independently)** - Version projects independently or together
- **[Release Groups](/docs/guides/nx-release/release-groups)** - Organize projects into release groups with specific configuration for each group
- **[Conventional Commits](/docs/guides/nx-release/automatically-version-with-conventional-commits)** - Automate versioning based on commit messages
- **[Custom Registries](/docs/guides/nx-release/configure-custom-registries)** - Publish to private or alternative registries
- **[CI/CD Integration](/docs/guides/nx-release/publish-in-ci-cd)** - Automate releases in your pipeline
- **[Changelog Customization](/docs/guides/nx-release/configure-changelog-format)** - Control changelog generation and formatting
- **[Custom Commit Types](/docs/guides/nx-release/customize-conventional-commit-types)** - Define custom conventional commit types
- **[Version Prefixes](/docs/guides/nx-release/configuration-version-prefix)** - Configure version prefix patterns

### Workflows

- **[Automate with GitHub Actions](/docs/guides/nx-release/automate-github-releases)** - Set up automated releases in GitHub workflows
- **[Release Projects Independently](/docs/guides/nx-release/release-projects-independently)** - Manage independent versioning for projects
- **[Use Conventional Commits](/docs/guides/nx-release/automatically-version-with-conventional-commits)** - Enable automatic versioning from commits
- **[Build Before Versioning](/docs/guides/nx-release/build-before-versioning)** - Run builds before version updates

### References

- **[`nx.json` configuration options](/docs/reference/nx-json#release)** - All available options for configuring `nx release`
- **[`nx release` command](/docs/reference/nx-commands#nx-release)** - Run versioning, changelog generation, and publishing
- **[`nx release version` command](/docs/reference/nx-commands#nx-release-version)** - Run only the versioning step
- **[`nx release changelog` command](/docs/reference/nx-commands#nx-release-changelog)** - Run only the changelog generation step
- **[`nx release publish` command](/docs/reference/nx-commands#nx-release-publish)** - Run only the publishing step
- **[`nx release plan` command](/docs/reference/nx-commands#nx-release-plan)** - Create a version plan file for file-based versioning