Skip to content

Publish to NPM registry workflows

Jump to bottom
Tony Gaskell edited this page Aug 12, 2025 · 2 revisions

This document outlines the automated workflows for publishing packages to the NPM registry. These workflows ensure repeatability, consistency, and visibility for open-sourced projects by providing a standardized process for version management and package publication.

Publish via GitHub

The publish workflows can be triggered directly from the GitHub Actions interface:

Inputs

version_type (required): The type of version bump to perform. Options include:

  • major: Increments the major version (e.g., 1.0.0 → 2.0.0)
  • minor: Increments the minor version (e.g., 1.0.0 → 1.1.0)
  • patch: Increments the patch version (e.g., 1.0.0 → 1.0.1)
  • premajor: Creates a prerelease for the next major version (e.g., 1.0.0 → 2.0.0-rc.0)
  • preminor: Creates a prerelease for the next minor version (e.g., 1.0.0 → 1.1.0-rc.0)
  • prepatch: Creates a prerelease for the next patch version (e.g., 1.0.0 → 1.0.1-rc.0)
  • prerelease: Increments the prerelease version (e.g., 1.0.0-rc.0 → 1.0.0-rc.1)

Prerelease Strategy

When working with prereleases:

  1. Start with one of: premajor, preminor, or prepatch to create the initial release candidate (e.g., 1.1.0-rc.0)
  2. Use prerelease for subsequent release candidate bumps (e.g., 1.1.0-rc.0 → 1.1.0-rc.1 → 1.1.0-rc.2)
  3. When ready for the final release, use major, minor, or patch as appropriate

Publish via GitHub CLI

The GitHub CLI provides a powerful way to trigger workflows from the command line, allowing you to run workflows against any branch:

gh workflow run <publish-radfish.yml, or publish-react-radfish.yml> --ref <branch-name> -f version_type=<version_type_input>

Examples:

# Publish a patch release from main branch
gh workflow run publish-radfish.yml --ref main -f version_type=patch

# Create a prerelease from a feature branch
gh workflow run publish-react-radfish.yml --ref feature/new-component -f version_type=preminor

# Bump an existing prerelease
gh workflow run publish-radfish.yml --ref develop -f version_type=prerelease

The ability to run workflows against branches other than the default branch (main) is particularly useful for:

  • Creating prereleases from experimental or development branches
  • Testing the publication process without affecting the main branch
  • Managing multiple release trains simultaneously

Tagging

Upon successfully publishing a package to npm, the workflow automatically creates a git tag with the format <package-name>@<version>. For example:

These tags serve as permanent references to the exact code state at the time of publication, enabling:

  • Easy rollback to previous versions
  • Clear version history tracking
  • Reproducible builds from any published version

The tagging process occurs after the npm publish step succeeds, ensuring that only successfully published versions are tagged in the repository.

Release Notes

GitHub releases are automatically generated when a package is successfully published and tagged. The workflow creates a GitHub release that includes:

  • Release Title: The package name and version (e.g., "@nmfs-radfish/[email protected]")
  • Tag Reference: Links to the git tag created during the publishing process
  • Release Type: Marked as a prerelease for any version containing -rc, -beta, or other prerelease identifiers
  • Automated Changelog: GitHub automatically generates release notes based on:
    • Merged pull requests since the last release
    • Commit messages between releases
    • Contributors who participated in the release

This automated release creation provides:

  • A centralized location for viewing all package releases
  • Easy access to changelogs for each version
  • Clear visibility into what changes are included in each release
  • Direct links to download specific versions of the published packages

Clone this wiki locally