Choosing npm for Release Management

Hello!! 👋

When it came time to choose a release tool and package registry for my project, I opted for npm. Its ubiquity, ease of use, and integration with modern CI/CD workflows made it the ideal choice for my needs.

Creating a Release: Step-by-Step Process

Here’s a detailed breakdown of the steps I took to create a release with npm for my project Barrierless:

1. Set Up an npm Account and Token

First, I created an account on npm. After logging into my account, I generated an npm token from my profile settings. This token is crucial for authenticating with npm during the release process.

I then stored this token in my project’s GitHub repository under Settings > Secrets and variables > Actions > New repository secret, using the key NPM_TOKEN. This ensures that my GitHub Actions workflows can securely access the token without exposing it publicly.

2. Configure a GitHub CD Pipeline

Next, I created a GitHub Actions pipeline file, cd.yml, in the .github/workflows/ directory. This file automates the release process. Here's a simplified example of what the pipeline might look like:

name: CD Pipeline

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
          registry-url: 'https://registry.npmjs.org/'

      - name: Install dependencies
        run: npm install

      - name: Publish to npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm publish

3. Prepare the Release

After making updates to my project, I:

1. Staged and committed my changes:

   git add .
   git commit -m "Prepare for release"

1. Created a new version tag using npm:

   npm version patch

This automatically updates the version in package.json and creates a corresponding Git tag.

1. Pushed everything to the remote repository:

   git push origin main --tags

4. Create a GitHub Release

On GitHub, I navigated to Releases, clicked Draft a new release, and selected the tag for the latest version. After providing a description, I published the release. This action triggered the CD pipeline.

5. Verify the Release

Once the pipeline completed successfully, my package was published to npm and ready for users to install.

Lessons Learned

"Aha!" Moment: Missing NPM_TOKEN

Initially, my pipeline failed with an error stating that NPM_TOKEN was missing. This was because I hadn’t set up the GitHub secret correctly. Once I added the secret, the pipeline ran smoothly.

Iteration and Debugging

I had to iterate several times to get the process right. Determining the correct order of steps and ensuring all dependencies were properly configured took some trial and error. For example, I forgot to remove extraneous console.log statements from test cases during my first release, which caused confusion during user testing.

User Testing

I asked my buddy, Peter Wan, to test my CLI tool by installing it directly from the npm registry. Initially, he encountered unexpected console.log outputs. After fixing this issue and publishing a new release, Peter successfully tested the updated version.

This exercise reinforced the importance of thorough testing and cleanup before publishing.

Installing and Using the Project

Now that the project is released, users can install it directly from npm. Here’s how:

1. Install the package globally:

   npm install -g barrierless

1. Use the CLI tool:

   bl-bot -v