Versioning and Publishing Packages with Nx Release

Rate this content

Learn to publish npm packages like a pro using the power of Nx. Starting from a basic repo with several packages, we'll establish a versioning strategy, changelog structure, and publishing workflow. Afterwards, we'll explore the many features and options of Nx release that allow you to adapt to your organization's processes.

10 min
15 Feb, 2024

Video Summary and Transcription

In this Talk, Austin Faisal introduces Nx Release and demonstrates how to improve versioning and publishing processes with it. The tool allows for a dry run to preview changes, keeps packages in sync, and generates changelogs. It also automates staging, committing, tagging, and publishing changes to the registry. Nx Release offers additional features such as independent versioning, automatic versioning with conventional commits, creating GitHub releases, customizable changelog rendering, and a programmable API.

Available in Español

1. Introduction to Nx Release

Short description:

Hi, my name is Austin Faisal. I'm a core maintainer of Lerna, a member of the Nx core team, and I'm going to show you how to level up your versioning and publishing process with Nx Release. We'll initialize Nx in an existing repo, pick a new version for our packages, generate a workspace-level changelog file, and publish all of our packages to the remote registry. Then we'll cover additional features that Nx Release has to offer. Let's get started.

Hi, my name is Austin Faisal. I'm a core maintainer of Lerna, a member of the Nx core team, and I have a background in enterprise web development. And I'm going to show you how to level up your versioning and publishing process with Nx Release.

First, we'll initialize Nx in an existing repo. Then we'll use Nx Release to pick a new version for our packages, generate a workspace-level changelog file, and publish all of our packages to the remote registry. Then we'll cover some additional features that Nx Release has to offer. Let's get started.

So we're starting from a basic JavaScript monorepo. It's using npm workspaces, and it has three packages, inventory, requests, and users. The first thing we're going to do is we're going to initialize Nx and we're going to install the NxJS plugin. So I'm going to answer a few of these questions. None of the scripts need to be run in order, so I'll go ahead and hit enter. None are cacheable and I am not going to enable remote caching. However, I would definitely encourage you to look into remote caching for your own workspace because it can save a lot of time in CI and in your local workflow. But for this example, I'm going to stay focused on Nx Release and just go ahead and skip that.

Okay, now I'm going to go into the NxJSON file and we're going to tell Nx exactly which packages we want to publish. We're going to do this with the project property under release. This is important because even though Nx will see all of the projects in your repo, you don't necessarily want to publish all of them because you might have applications or end testing projects or other things that aren't npm packages that you want to publish. So in this case, we have three packages we want to publish. They're all under the packages folder and so we can use this glob to represent that.

Okay, and then let's go ahead and commit our changes so far. We'll do this so that we have a nice fresh working tree from here on. And then I'm going to go ahead and add one more change. I'm going to actually fix a nasty bug in the inventory data. And usually it's a lot harder to fix a bug than just add a comment, but this will work for what we need to do. So I'm going to go ahead and commit this change as well. And then now we can run Nx Release. So I'm going to go ahead and run Nx Release first release dry run. And these two options are very important. The first release option indicates to Nx that this is the first time we're running Nx Release.

2. Running Nx Release and Reviewing Changes

Short description:

The dry run option allows you to preview the changes without actually writing them to disk or publishing the packages. Nx Release keeps your packages in sync by default, ensuring easy compatibility for consumers. The package JSON files are updated with the new version, and dependencies are also updated. The generated changelog includes the added packages and the recent bug fix.

So it shouldn't worry about any validation around previous get tags or making sure that the packages exist in the remote registry. And the dry run option is going to perform this as a dry run. It's going to not actually write any changes to disk. It's going to skip all the get operations. It's not actually going to publish the packages. It's just going to give us a preview of what would happen if we didn't use dry run. And so this is very valuable when we're dealing with these really hard to undo operations like creating get tags, creating GitHub releases, publishing packages to the registry.

So I'm going to go ahead and run it. And I'm going to pick a minor version. So it's going to prompt for what kind of change is this. And I'm going to say minor. OK. So the command finished. And let's go back up to the top and see what happened. The first step is versioning. So it detects each of these three projects, inventory, requests, users. It reads the current version of each as 0.0.1 from the package JSON file. And then it writes the new version based on that minor bump we told it to do. The new version being 0.1.0 writes it to each of the three package JSON files. Now NxRelease will always keep your packages in sync by default. So whenever you want to increment the version of any of them, it will increment the version of all of them. And so you'll always be releasing the same version number for each of your packages. This is recommended because it makes it really easy for the consumers of your package to figure out which versions are compatible. Because if they've all got the same version number, it's just very, very clear.

So if we keep scrolling down, we can see the changes to the package JSON files. And you'll note that the requests package actually has a dependency on the users package. And that was updated as well by NxRelease. And then we get down here, we could see the changelog that would be generated. So the changelog has one feature, which is the feature in which I added the users requests and inventory packages previously. And then there's the fix that we just did to the inventory package.

3. Publishing Changes to the Registry

Short description:

We get a preview of the git commands and a reminder that the dry run was just a preview. After confirming all the changes, including package JSON and lock file updates, NxRelease will stage, commit, and tag the changes before publishing them to the registry.

And then at the end, we get a preview of our git commands and a reminder that because we used dry run, none of this actually happened. It was just a preview. So seeing that that is as we expected it to be, I can go ahead and remove the dry run option and run it again. I'm still going to pick minor. And you'll see that it's mostly the same, but we get a prompt at the end. So you want to publish these versions. Now, before I respond to that, I want to scroll up and just double check. So yep, we got all of our versions being bumped, 0.1.0. Our package JSON changes look good. The lock files being updated because the lock file has data about the version of each package in your workspace. And since we've changed those, we need to change the lock file. And then we've got this changelog that we just looked at that looks good. And then lastly, it will stage, commit, and tag the changes. So I'm going to go ahead and hit yes. And then it's going to go ahead and publish. As easy as that. So it just runs npm publish on each of these packages. And you'll see it went ahead and published to localhost because I'm hosting a local registry at the moment. But this is just whatever your npm, yarn, whatever other registry you have configured.

4. Additional Features and Customization Options

Short description:

NxRelease supports independent versioning of packages, automatic versioning with conventional commits, creating GitHub releases, customizable changelog render, and a robust programmatic API for custom scripts.

And that's it. So let's talk about a couple additional features. So I mentioned that by default, that will keep all of the versions of your packages in sync. Well, there are other ways to do it. You can definitely version your packages independently, where each package has potentially a different version and you don't always release all your packages at once. That's definitely something that NxRelease supports. You just have to add a couple configuration options.

Then you can also configure automatic versioning with conventional commits. So if you don't want to have to deal with a prompt or explicitly specifying that you want a minor version or a major version or a patch version, you can opt into using conventional commits for that. So if your commits in your repo follow the conventional commits standard, then NxRelease will be able to look at your Git history since the last release and determine which kind of version bump to do for each of the packages.

A few other things. So NxRelease can also create GitHub releases. That's something that you can opt into and the changelog files that are generated will automatically be pushed up for the pages on GitHub releases. You can swap out the changelog render. So if you don't like the markdown that's generated by default, then you can plug in a function that gets given all of the commit data and returns whatever markdown you want it to. And then lastly, NxRelease has a very robust programmatic API. So if you've got your own scripts for releasing, your own versioning, publishing scripts, you can actually plug NxRelease into that. So the three major building blocks of NxRelease, version, changelog, and publish, you can import each of them individually into your own scripts. So you can use them, you can use any one of them or all three of them, however you want to make your own process that works for you. And that's it. Thank you for listening. Please check out the docs that will explain all of this even more. It'll go into the different configuration options and different use cases. And I look forward to seeing you in the future.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

DevOps.js Conf 2022DevOps.js Conf 2022
31 min
pnpm – a Fast, Disk Space Efficient Package Manager for JavaScript
You will learn about one of the most popular package managers for JavaScript and its advantages over npm and Yarn.A brief history of JavaScript package managersThe isolated node_modules structure created pnpmWhat makes pnpm so fastWhat makes pnpm disk space efficientMonorepo supportManaging Node.js versions with pnpm
JSNation 2022JSNation 2022
28 min
Yarn 4 - Modern Package Management
Top Content
Yarn 4 is the next major release of your favourite JavaScript package manager, with a focus on performance, security, and developer experience. All through this talk we'll go over its new features, major changes, and share our long-term plans for the project.If you only heard about Yarn without trying it yet, if you're not sure why people make such a fuss over package managers, if you wonder how your package manager can make your work simpler and safer, this is the perfect talk for you!
JSNation 2022JSNation 2022
20 min
Immutable Web Apps
Resolving dependencies when they are all bundled together is easy. Resolving dependencies when they are in being loaded via script tags is much more challenging. The goal of this talk is to explain how Meltwater handles dependency resolution when building native Web Component based applications that rely on packages published by many different teams.
DevOps.js Conf 2021DevOps.js Conf 2021
26 min
What's New in npm?
The npm CLI has been, & continues to be, a core developer tool of the Node.js/JavaScript ecosystem. This past year npm@7 became Generally Availble, introducing with it a wealth of changes & net-new capabilities including: lockfile upgrades, workspace support, installing peer dependencies default, npm diff, npm explain, npm exec, npm set-script & much, much more. We'll dive into this work as well as share some exciting news about what to expect in the weeks & months to come.