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.
Versioning and Publishing Packages with Nx Release
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.
1. Introduction to Nx Release
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
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.
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
Comments