npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@releasekit/release

v0.47.0

Published

Unified release pipeline: version, changelog, and publish in a single command

Readme

@releasekit/release

[!WARNING] 🚧 Pre-1.0.0 — ReleaseKit is evolving fast and 💥 breaking changes are common; it's not production-ready until v1.0.0. Pin exact versions. See the main README for details.

@releasekit/release Version Downloads

Unified release pipeline: version, changelog, and publish in a single command.

Features

  • Single command — runs version, notes, and publish as one pipeline
  • Programmatic orchestration — calls each tool's API directly, no subprocesses
  • CI-friendly — exits cleanly (code 0) when there are no releasable changes
  • Skippable steps — skip notes, publish, git, or GitHub releases independently
  • Dry-run mode — preview the full pipeline without side effects
  • JSON output — structured results for scripting and CI integration
  • Monorepo support — target specific packages or version all in sync

Installation

npm:

npm install -g @releasekit/release

pnpm:

pnpm add -g @releasekit/release

Note: This package is ESM only and requires Node.js 22.12+.

Quick Start

# Preview what would happen
releasekit release --dry-run

# Run a full release
releasekit release

# Force a patch bump
releasekit release --bump patch

# Version and publish, skip changelog generation
releasekit release --skip-notes

Pipeline

The release command runs three steps in order:

  1. Version — analyse conventional commits and calculate the next semver bump
  2. Notes — generate changelog from the version output (skippable)
  3. Publish — git commit/tag, npm/cargo publish, GitHub release (skippable)

If no releasable changes are found after step 1, the command exits with code 0 and skips the remaining steps.

In GitHub Actions it first reads the labels of the merged PR the pushed commit came from, as gate does. It exits 0 when they don't call for a release, and otherwise takes the bump, channel and scope from them. See Merged-PR labels.

CLI Reference

Flags for every command are in the CLI reference: release, preview, gate, standing-pr, refresh-after-release, backfill, init and labels.

Usage Examples

In CI (GitHub Actions)

- name: Release
  run: pnpm exec releasekit release
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    # For OIDC trusted publishing: no npm token needed (recommended).
    # For token-based publishing: set NPM_TOKEN (or NODE_AUTH_TOKEN).

examples/ci/minimal runs this on every push to main. examples/ has the other workflows.

Monorepo with targeted release

# Release only specific packages
releasekit release --target @myorg/core,@myorg/cli

# Release all packages in sync
releasekit release --sync

Prerelease workflow

# Create new prerelease from stable version
releasekit release --prerelease beta

# Increment existing prerelease version
releasekit release --bump prerelease

Gate mode in CI

release makes the gate's decision itself, so one release step is enough. Run gate as its own job to skip the release job's setup when nothing will release:

jobs:
  gate:
    runs-on: ubuntu-latest
    outputs:
      should-release: ${{ steps.gate.outputs.should-release }}
    steps:
      - id: gate
        uses: goosewobbler/releasekit@v0
        with:
          mode: gate

  release:
    needs: gate
    if: needs.gate.outputs.should-release == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: goosewobbler/releasekit@v0
        with:
          mode: release

Programmatic API

import { runRelease, runGate } from '@releasekit/release';

// Full release
const result = await runRelease({
  dryRun: true,
  bump: 'minor',
  skipNotes: false,
  skipPublish: false,
  skipGit: false,
  skipGithubRelease: false,
  skipVerification: false,
  sync: false,
  json: false,
  verbose: false,
  quiet: false,
  projectDir: process.cwd(),
});

if (result) {
  console.log(`Released ${result.versionOutput.updates.length} packages`);
} else {
  console.log('No releasable changes');
}

// Gate check
const gateResult = await runGate({
  projectDir: process.cwd(),
  json: true,
});

console.log(`Should release: ${gateResult.shouldRelease}`);
console.log(`Bump: ${gateResult.bump}`);
console.log(`Scope: ${gateResult.scope}`);
console.log(`Target: ${gateResult.target}`);

Configuration

Create a releasekit.config.json in your project root. Add $schema for editor autocompletion and validation:

{
  "$schema": "https://goosewobbler.github.io/releasekit/schema.json",
  "version": {
    "preset": "angular",
    "packages": ["./"]
  }
}

The release command reads the version, notes, and publish sections. See the individual package READMEs for all available options:

CI Configuration

The ci section controls automation behavior:

{
  "ci": {
    // How releases are delivered
    "releaseStrategy": "direct",       // "manual" | "direct" | "standing-pr"

    // What triggers a release
    "releaseTrigger": "label",         // "commit" | "label"

    // Enable/disable PR preview comments
    "prPreview": true,

    // Map PR labels to package filters for scoped releases
    // Example: a PR with "scope:shared" label only releases matching packages
    "scopeLabels": {
      "scope:shared": "@myorg/shared-*",
      "scope:frontend": "@myorg/web-*"
    }
  }
}

Every ci.* key, including the label names under ci.labels, is in the configuration reference.

Release Trigger

label (default) — A PR label (bump:patch, bump:minor, or bump:major) is required to trigger a release. The label determines the bump type. PRs without a release label will not trigger a release when merged.

commit — Conventional commits drive the bump type automatically. Every merge can trigger a release. Use the release:skip label to prevent a release, or bump:major to override the commit-derived bump to major.

Both modes support release:graduate and channel:prerelease. release:graduate alone graduates any prerelease packages to their stable base version and skips packages that are already stable — no bump label required (it's a standalone release-flow trigger). channel:prerelease makes the release a prerelease; with the label trigger it also needs a bump:* label.

Standing-pr strategy is different. When releaseStrategy: "standing-pr", labels on feeder PRs are advisory only — the standing PR itself is the canonical override surface (add bump:major etc. to the standing PR to drive the next release). To bypass the queue and ship one PR directly, label it release:immediate. See CI setup → Label semantics in standing-pr mode.

Release Strategy

| Strategy | Description | |----------|-------------| | direct | Release is triggered when a PR is merged to the main branch | | manual | Releases are triggered manually (e.g. via workflow_dispatch) | | standing-pr | Changes accumulate in a standing release PR, merged when ready |

Scope-Based Release

Use scopeLabels to filter which packages are released based on PR labels. This is useful for monorepos with distinct package groups.

When the PR that decides the release has a matching scope label, only packages matching the pattern are included in the release:

{
  "ci": {
    "scopeLabels": {
      "scope:shared": "@myorg/shared-*",
      "scope:ui": "@myorg/ui-*"
    }
  }
}

Usage:

  • scope:shared + bump:minor → Release only @myorg/shared-* packages with minor bump
  • scope:shared alone → Release only shared packages under the commit trigger, bump from conventional commits; no release under the label trigger
  • No scope label → Release every package with releasable changes

A PR's first matching scope label applies. --target or --scope replace it.

Label conflicts:

Conflicting labels on a PR block the release, and gate comments on the PR to explain:

  • Multiple bump labels (bump:major + bump:minor + bump:patch) → blocked in label trigger mode, and on a release:immediate PR in standing-pr strategy
  • Conflicting release type (release:graduate + channel:prerelease) → blocked in both modes

How it works:

  • Preview mode: Reads labels directly from the PR
  • Release and gate modes: Read the labels of the merged PR the pushed commit came from. See Merged-PR labels.

Standing PR Configuration

When releaseStrategy: "standing-pr", the ci.standingPr block tunes the bot-maintained release PR. All keys are optional; see ci.standingPr in the configuration reference.

{
  "ci": {
    "releaseStrategy": "standing-pr",
    "standingPr": {
      "branch": "release/next",
      "mergeMethod": "squash",
      "minAge": "6h"
    }
  }
}

See CI setup — Standing Release PR for prerequisites (required GitHub repo setting, secrets), lifecycle behaviour, and troubleshooting. The workflow is examples/ci/standing-pr.

PR Preview

The releasekit preview command posts a comment on pull requests showing what would be released. It reads PR labels from GitHub and adapts its messaging based on releaseStrategy and releaseTrigger.

Copy examples/ci/release-preview/release-preview.yml to .github/workflows/release-preview.yml. Its preview step:

- run: pnpm exec releasekit preview
  env:
    GITHUB_TOKEN: ${{ github.token }}

Documentation

Getting Started

  • CI Setup — how each CI setup works, including the standing PR
  • CI examples — the workflows, validated in CI

License

MIT