Create a Prerelease Channel in Your NPM Package using semantic-release

If you wish to thoroughly test essential features of your npm package in real-world scenarios before its official release, it's a good practice to establish a prerelease channel labeled as @beta to allow early testing.

By incorporating semantic-release into our Continuous Integration (CI) environment, we can automate the entire package release process. This tool determines the next version number by analyzing commit messages (including keywords like "fix," "feat," and "BREAKING CHANGE"), generates release notes, and publishes the package.

To set up a GitHub Action for this purpose, follow these steps:

Step 1: Define the GitHub Action Workflow

Create a workflows folder at the root of your project and include a release.yml file with minimal configuration settings for semantic-release. This workflow runs on Node.js version 18.


name: Release CI
on:
  push:
    branches: [main, next]
  pull_request:
    branches: [main, next]
jobs:
 ...

The on section specifies the triggers. In this case, the workflow "Release CI" will execute when a new commit is pushed or merged to the main or next branch.

Step 2: Add the Prerelease Channel

2.1 - Update triggers in release.yml

To incorporate the beta channel as a trigger in the release.yml file, modify the on section as follows:


on:
  push:
-    branches: [main, next]
+    branches: [main, next, beta]
  pull_request:
-    branches: [main, next]
+    branches: [main, next, beta]

Now, this workflow will release a new version in the beta channel every time there's a push or pull request merge in the beta branch.

2.2 - Configure the package.json

In your library's package.json file, within the release option, add the new beta branch with prerelease: true.


"release": {
  "branches": [
    // other branches
    {
      "name": "beta",
      "prerelease": true
    }
  ]
},

After making these changes, commit them to the main branch using the following commands:


git add .
git commit -m "chore: add beta prerelease channel"
git push

2.3 - Create the beta branch in your repository

Create a new branch named "beta" in your Git repository by running the command:


git branch beta

Then, create the branch in your hosted repository using:


git push --set-upstream origin beta

Now, whenever you merge changes into the beta branch, you can test your package as a prerelease in your real projects by installing it with your-package@beta.

With these steps, you've set up a prerelease channel for your npm package, making it easier to test and gather feedback before the official release.

Transcript

[00:00] If you want to test some critical features of your NPM package in real-world scenarios before releasing them, it could be nice to have a pre-release channel, like the one we have here, called Next, and be able to try it out first. To achieve that in our package,

[00:18] we will be using the tool Semantic Release. This tool help us automate the whole package release workflow, including determining the next version number, generating the release nodes for all the changes, and publishing the package to the NPM registry.

[00:34] Let's see now how we can add that to our library. As our project is host on GitHub, we can create a GitHub action by defining a workflows folder and a release.yaml file. The release.yaml content is a minimal configuration for Semantic Release,

[00:53] running on the 18 version of Node, building our library, and then testing that the library is working nice before releasing it. This process will be executed when a trigger happens. In this case, what we want is every time we create a pull request and then merge it to this branch,

[01:12] we want to execute this job, and the same when we push content to the branches main and next. In this case, as we want to add a pre-release channel, let's add a new branch to trigger this action. This branch will be beta. So you can add it as a trigger

[01:33] for the pull request and push actions. Now that we have it, we can go to the package.json of our library and add the pre-release channel as part of the branches in release.

[01:53] So now we have a branch called beta in pre-release to true. So now let's push the changes to the main branch and let's run

[02:04] git add dot then git commit dash m core add beta pre-release channel.

[02:21] We can run git push. Perfect. Let's clear the terminal. Now that we have defined the trigger in the pre-release channel beta in our package.json, let's add a branch in our repo to actually make these changes happen.

[02:44] Let's run the command git branch beta. Now we have created the branch, but we need to push it to our repo. So let's run the command git push dash dash set dash upstream origin beta.

[03:01] We are pushing our branch to the repo so we have it ready. Now we have everything we need to have a pre-release channel beta. So let's try it out. Let's now check out the beta branch with git checkout beta. Now that we are here,

[03:20] we can change something in our repo and commit it to see the pre-release happen. Let's change the name of the author, for example, adding the role. Once we save it, we can add it to our changes in git and then

[03:37] commit it as a fix in order to see the pre-release happen. Otherwise, will not be pre-released. Let's run the command git push that will trigger our release YAML.

[04:02] Now we can go back to our repository and check the actions. You can see that the latest that we executed was the fixed pre-release try we just push. If we open it, we can see that the release YAML was the one

[04:20] executed and the release was successful. Let's go now to the code and then open the releases again. So we can see that the beta pre-release channel has deployed a new version that we can try it out. Then when you are happy with the result,

[04:37] you can merge into main and you will release the latest package version.