Versioning and Publishing Packages with Nx Release

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.

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.

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.

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 Nx.dev 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.