VShell: Production Release Workflow

This week, I am preparing to release my command-line tool, VShell, to production. This release will enable users to install and use VShell directly via npm without the need to clone and build the project locally. Written in JavaScript with Node.js, the tool will be hosted on npm for ease of distribution. Below is a detailed breakdown of the steps I followed to achieve this release:

Automating the Build Process

To ensure a reproducible and automated build, I created a build.js script in the root of the project. This script copies all necessary files into a dist folder, simplifying the build process.

Besides, I also set up a script to run it in package.json:

"build": "node build.js"

To run it, just need to type: npm run build on the console

Currently, I just wanted to demonstrate a simply build as copying files, but in the future, if I implemented with the UI, then I would need to use template bundle script as barbel.

Implementing Semantic Versioning

Previously, I often forgot to update the project version after making changes. For this release, I adopted Semantic Versioning to clearly communicate changes in the project API.

Given the significant updates since v0.0.1, I set the version to v1.0.0 by updating the version field in package.json. This version reflects a stable API with breaking changes and new features.

Tagging the Release in Git

To synchronize the version update with GitHub releases, I created a Git tag for v1.0.0:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin --tags

This ensures that the release is properly tracked in the Git repository.

Declaring Package Files

To publish VShell as an npm package, I explicitly defined the files to include in the package using the files field in package.json. This ensures that only the necessary files and directories are included in the published package.

Example:

Publishing to npm

To publish VShell on npm:

• Sign Up and Log In: I created an npm account and logged in using: npm login
• Publishing: Once authenticated, I published the package: npm publish

This made VShell available to users via npm.

Out of scope updates

GitHub Dependabot flagged a security issue with the transitive dependency cross-spawn. Since I didn’t install it directly, I used:

npm ls cross-spawn

to identify which package depended on it. I discovered that eslint was the source and resolved the issue by updating eslint to the latest version.

Additionally, I updated the README.md to provide clear installation instructions for npm users. I also improved the CONTRIBUTING.md file to guide contributors on setting up and running VShell locally.

To enhance accuracy, I incorporated feedback from Prof. David Humphrey, expanding and clarifying the GROQ system documentation.

Automating Releases with GitHub Actions

To streamline the release process, I added a job to my GitHub Actions workflow to automate npm publishing whenever a new tag is pushed.

Workflow Addition:

release:
    needs: build

    runs-on: ubuntu-latest

    if: startsWith(github.ref, 'refs/tags/')

    permissions:
      contents: write

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

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: 22.x
        registry-url: 'https://registry.npmjs.org'

    - name: Install dependencies
      run: npm ci

    - name: Build project
      run: npm run build

    - name: Update version
      run: npm version ${{ github.ref_name}} --no-git-tag-version

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

    - name: Create GitHub release
      uses: softprops/action-gh-release@v1
      with:
        name: Release ${{ github.ref_name}}
        draft: false
        prerelease: false
        token: ${{ secrets.GITHUB_TOKEN }}

Key Features:

Conditional Trigger: The release job is triggered only when a tag (v*.*.*) is pushed.

npm Authentication: Using a secure NPM_AUTH_TOKEN stored in GitHub Secrets. You can create this token by going to your npm account and choose Access Token section.

GitHub Release: Automatically generates a release using softprops/action-gh-release.

Conclusion

By following these steps, I successfully automated the release of VShell to npm. Users can now install and use the tool effortlessly via:

npm install -g vshell

This streamlined process, coupled with proper versioning, dependency management, and documentation updates, ensures a professional and user-friendly release of VShell.