Manage Releases - nx release
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?
A release can be thought about in three main phases:
- Versioning - The process of determining the next version of your projects, and updating any projects that depend on them to use the new version.
- 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.
- 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.
❯
nx release --first-release --dry-run
By default, the version follows semantic versioning (semver) rules. To disable this behavior, set release.releaseTagPatternRequireSemver to false in your nx.json file. This allows you to use custom versioning schemes.
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
Configure Nx Release in your nx.json file:
1{
2 "release": {
3 "projects": ["packages/*"]
4 }
5}
6The 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
For maximum control, use the programmatic API to create custom release workflows:
1import { releaseChangelog, releasePublish, releaseVersion } from 'nx/release';
2import * as yargs from 'yargs';
3
4(async () => {
5 const options = await yargs
6 .version(false) // don't use the default meaning of version in yargs
7 .option('version', {
8 description:
9 'Explicit version specifier to use, if overriding conventional commits',
10 type: 'string',
11 })
12 .option('dryRun', {
13 alias: 'd',
14 description:
15 'Whether or not to perform a dry-run of the release process, defaults to true',
16 type: 'boolean',
17 default: true,
18 })
19 .option('verbose', {
20 description:
21 'Whether or not to enable verbose logging, defaults to false',
22 type: 'boolean',
23 default: false,
24 })
25 .parseAsync();
26
27 const { workspaceVersion, projectsVersionData } = await releaseVersion({
28 specifier: options.version,
29 dryRun: options.dryRun,
30 verbose: options.verbose,
31 });
32
33 await releaseChangelog({
34 versionData: projectsVersionData,
35 version: workspaceVersion,
36 dryRun: options.dryRun,
37 verbose: options.verbose,
38 });
39
40 // publishResults contains a map of project names and their exit codes
41 const publishResults = await releasePublish({
42 dryRun: options.dryRun,
43 verbose: options.verbose,
44 // 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)
45 // It will then be provided to the publish executor options as `nxReleaseVersionData`
46 // This is not required for the default @nx/js publish executor
47 versionData: projectsVersionData,
48 });
49
50 process.exit(
51 Object.values(publishResults).every((result) => result.code === 0) ? 0 : 1
52 );
53})();
54Learn More
Configuration & Customization
- Release Groups - Version projects independently or together
- Conventional Commits - Automate versioning based on commit messages
- Custom Registries - Publish to private or alternative registries
- CI/CD Integration - Automate releases in your pipeline
- Changelog Customization - Control changelog generation and formatting
- Custom Commit Types - Define custom conventional commit types
- Version Prefixes - Configure version prefix patterns
Workflows
- Automate with GitHub Actions - Set up automated releases in GitHub workflows
- Release Projects Independently - Manage independent versioning for projects
- Use Conventional Commits - Enable automatic versioning from commits
- Build Before Versioning - Run builds before version updates
References
- Configuration in
nx.json- All available options for configuringnx release