DEV Community

AnhChienVu
AnhChienVu

Posted on

VShell: Production Release Workflow

#githubactions #javascript #opensource #openai

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.

Image description

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
Enter fullscreen mode Exit fullscreen mode

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:

Image description

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 }}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)