> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nrwl/nx/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

```bash theme={null}
nx release --dry-run
```

## What makes up a release?

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

<Steps>
  <Step title="Versioning">
    Determine the next version for each project and update any projects that depend on them. Versions follow semantic versioning (semver) by default.

    ```bash theme={null}
    nx release version
    # or with an explicit specifier:
    nx release version minor
    ```
  </Step>

  <Step title="Changelog generation">
    Derive a changelog from commit messages or version plan files and write it to `CHANGELOG.md`.

    ```bash theme={null}
    nx release changelog 1.2.0
    ```
  </Step>

  <Step title="Publishing">
    Publish packages to a registry (e.g. npm, crates.io, a Docker registry).

    ```bash theme={null}
    nx release publish
    ```
  </Step>
</Steps>

## Run the full release

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

```bash theme={null}
# 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:

```jsonc theme={null}
// nx.json
{
  "release": {
    "projects": ["packages/*"]
  }
}
```

### Configure versioning

```jsonc theme={null}
// 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

```jsonc theme={null}
// nx.json
{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "createRelease": "github"
      },
      "projectChangelogs": true
    }
  }
}
```

### Configure git operations

```bash theme={null}
# Commit, tag, and push as part of versioning
nx release version --git-commit --git-tag --git-push
```

Or configure defaults in `nx.json`:

```jsonc theme={null}
// 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:

```jsonc theme={null}
// 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:

```bash theme={null}
nx release --groups=npm-packages
nx release version --groups=npm-packages minor
```

## Publish options

```bash theme={null}
# 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:

```typescript theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
nx release plan:check
```

<CardGroup cols={2}>
  <Card title="nx release CLI reference" icon="terminal" href="/reference/cli/release">
    Full reference for all nx release subcommands and flags.
  </Card>

  <Card title="nx.json release configuration" icon="gear" href="/reference/nx-json">
    Configure release groups, versioning strategy, and changelog in nx.json.
  </Card>

  <Card title="CI setup" icon="server" href="/guides/ci-setup">
    Set up automated releases in GitHub Actions, GitLab, or other CI providers.
  </Card>

  <Card title="Extend Nx" icon="puzzle-piece" href="/extending-nx/overview">
    Write custom generators and executors to customize your release workflow.
  </Card>
</CardGroup>