npm Package Release

Release your npm package from GitHub Actions without maintaining custom release scripts or storing an npm publish token.

Implements Releases as Code for JavaScript packages. Release from GitHub Actions, test your package and run its lint checks, publish to npm, optionally update the changelog, create a Git tag and GitHub Release, and prepare the next development iteration. Compose workflows from classes with strong types. See rust-crate-release and ruby-gem-release for similar projects in the Rust and Ruby ecosystems.

Installation

Requires Node.js 22.14+ and npm 11.5.1+; the release workflow defaults to Node.js 26/npm 12.

npm install --save-dev --save-exact npm-package-release@0.2.0

The CLI is npr, but do not install the unrelated npm package npr.

Usage

1. Configure Your Package

Create npr.config.js:

import { KeepAChangelog, ReleaseWorkflow } from "npm-package-release";

export default new ReleaseWorkflow({
  changelog: new KeepAChangelog(),
});

Use a numeric package version, a GitHub repository URL, and a CHANGELOG.md with ## [Unreleased] and real notes. KeepAChangelog is also the default when omitted. Default validation runs npm test and npm run lint. For CommonJS projects, use npr.config.mjs and set the workflow's config input accordingly.

2. Add the Release Workflow

Add .github/workflows/release.yml using the caller example:

name: Release

on:
  workflow_dispatch:
    inputs:
      version:
        description: Optional numeric release version.
        type: string
        required: false

permissions:
  contents: write
  id-token: write

jobs:
  release:
    uses: dblock/npm-package-release/.github/workflows/release.yml@v0.2.0
    with:
      version: ${{ inputs.version }}

Merge the caller and locked development dependency into your default branch. Upgrade the package and pinned workflow together.

3. Enable Trusted Publishing

In your GitHub repository → Settings → Environments, create release, restrict it to your default branch, and optionally require maintainer approval. Branch rules must allow release commits/tags to be pushed; see setup and branch permissions.

New npm package: First publish a tested archive manually. After verifying the first release, open your package on the npm website, select Settings → Trusted publishing, add a GitHub Actions publisher, and set:

Field	Value
Organization or user	Your GitHub owner.
Repository	Your package's repository, not this tool's repository.
Workflow filename	release.yml, the caller filename only.
Environment name	release.
Allowed actions	Enable direct npm publish, not stage-only.

No npm publish token or NODE_AUTH_TOKEN is needed. A new publisher must successfully publish within two days or expire; configure it when you are ready to release.

4. Make a Release

Review your changes, run tests, and dispatch from your default branch:

gh workflow run release.yml

This publishes the checked-in version and prepares the next patch version. After a manual first publication, select a new unpublished version; pass -f version=0.1.1 to override the checked-in version. Verify the run summary, registry version/checksums, and GitHub Release. Inspect recovery artifacts before retrying a failed run.

Configuration

See Detailed Usage for CLI/API commands and defaults; Changelog Templates for contribution prompts and categories; Lifecycle Hooks for ordered stage extensions; Composable Workflows for custom classes and services; and Semantic Releases for opt-in Conventional Commits versioning and generated notes.

Contributing

See CONTRIBUTING.md, DESIGN.md, CHANGELOG.md, RELEASING.md, UPGRADING.md, AGENTS.md, Detailed Usage, Changelog Templates, Updating Markdown Sections, Testing Custom Workflows, the Lifecycle Hook Example, Lifecycle Hooks, Composable Workflows, Execution Providers and Contexts, Recovery and Reconciliation, and Semantic Releases.

License

Distributed under the MIT License.