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

@varlet/release

v2.3.0

Published

publish all packages, generate changelogs and check commit messages

Readme

Intro

Varlet Release is a tool used for publishing all packages, generating change logs, and checking commit messages, relying on pnpm.

  • 📦 Out of the box: Zero-configuration release experience
  • 🤖 Interactive CLI: Friendly interactive terminal prompts
  • 🛠 Standardization: Validates Git Commit messages and generates standard changelogs
  • 🔗 Extensibility: Supports both CLI commands and Node.js API for deep customization

Varlet Release requires Node.js ^20.19.0 || >=22.12.0 and esm only.

If you are upgrading from v1 to v2, read the migration guide first.

Note: Varlet Release does not support OTP (one-time password) authentication. It is recommended to use a bypass token (an npm granular access token for automated publishing) to avoid authentication issues during the release process.

Quick Start

Install dependencies:

pnpm add @varlet/release simple-git-hooks -D

Add the following configuration to package.json:

{
  "scripts": {
    "prepare": "simple-git-hooks",
    "release": "vr release",
    "changelog": "vr changelog"
  },
  "simple-git-hooks": {
    "commit-msg": "pnpm exec vr commit-lint $1",
    "post-merge": "pnpm exec vr lockfile-check"
  }
}

Now you can:

  • Write commits following the Conventional Commits format, commit-lint will automatically validate them.
  • After pulling or merging code, lockfile-check will automatically detect lockfile changes (pnpm-lock.yaml, yarn.lock, package-lock.json) and reinstall dependencies.
  • Run pnpm release to start the interactive release workflow.

Usage

Features Overview

  • release - Automatically complete the standard workflow from version modification to publishing and creating git tags.
  • publish - Execute the npm publish process independently, usually suitable for CI/CD environments.
  • changelog - Automatically generate formatted changelogs based on Git Commit conventions.
  • commit-lint - Validate whether the Git Commit Message adheres to specifications, helping teams unify commit formats.
  • lockfile-check - Check the status of the project's lockfile and provide dependency update mechanisms when changes occur.

release

Description: The core functional collection for package release, integrating all release preparation and subsequent operations.

Use cases: Used when a new version needs to be released and all workspace changes have been committed. It guides through the publication via an intuitive command-line interaction.

Core Workflow:

  1. Interactively prompt and confirm the new version number (automatically calculate patch, minor, major upgrades).
  2. Execute the user-customized task function (e.g., modifying files, bundling assets).
  3. Automatically update the version number in the project's package.json.
  4. Generate the Changelog for the corresponding version.
  5. Automatically complete the Git commit and create a new version Tag.
  6. Publish the updated packages to npm.

CLI Commands:

Flags Reference:

Usage: vr release [flags...]

Flags:
      --remote string                 Remote repository name  # default: 'origin'
      --skip-npm-publish              Skip npm publish
      --skip-changelog                Skip generating changelog
      --skip-git-tag                  Skip git tag
      --npm-tag string                npm tag
      --check-remote-version          Check remote version
      --release-type string           Release type (patch, minor, major, prepatch, preminor, premajor), skip the release type prompt
  -y, --yes                           Skip refs and registry confirmation

Example:

# Release all packages and execute the full workflow
pnpm exec vr release

# Skip npm publishing
pnpm exec vr release --skip-npm-publish
# Skip generating changelog
pnpm exec vr release --skip-changelog
# Check remote version, interrupt execution if the identical version already exists
pnpm exec vr release --check-remote-version

# Non-interactive release (e.g. for CI or AI agents): specify the release type and skip all confirmations
pnpm exec vr release --release-type patch --yes

# Specify the git remote name for pushing tags (useful when multiple remotes are configured, e.g. upstream, fork)
pnpm exec vr release --remote upstream

Node API:

import { release } from '@varlet/release'

release({
  remote?: string              // Remote repository name, defaults to 'origin'
  npmTag?: string              // NPM tag to publish, such as 'next', 'alpha'
  cwd?: string                 // Working directory, defaults to process.cwd()
  skipNpmPublish?: boolean     // Whether to skip the npm publish process
  skipChangelog?: boolean      // Whether to skip changelog generation
  skipGitTag?: boolean         // Whether to skip git tag creation
  checkRemoteVersion?: boolean // Whether to check remote version to avoid conflicts
  releaseType?: 'patch' | 'minor' | 'major' | 'prepatch' | 'preminor' | 'premajor' // Release type, skips the release type prompt
  yes?: boolean                // Whether to skip refs and registry confirmation
  task?(newVersion: string, oldVersion: string): Promise<void> // Custom task executed during the release
})

Example: Add custom handling logic

import { release } from '@varlet/release'

async function task(newVersion, oldVersion) {
  // Execute building or file writing operations here
  await doBuild()
}

release({ task })

publish

Description: Publish the package independently to the npm registry.

Use cases: Applicable in scenarios where manual version selection, changelog generation, or git tags are not needed, often used in CI/CD pipelines to trigger automated publication based on specific processes.

Core Workflow: Read the version number from the current package.json and run the corresponding publish process.

CLI Commands:

Flags Reference:

Usage: vr publish [flags...]

Flags:
      --check-remote-version          Check remote version
      --npm-tag string                npm tag

Example:

# Publish directly to npm
pnpm exec vr publish

# Check if the same version already exists due to network or other reasons, and abort if so
pnpm exec vr publish --check-remote-version
# Specify the npm dist-tag
pnpm exec vr publish --npm-tag alpha

Node API:

import { publish } from '@varlet/release'

publish({
  preRelease?: boolean         // Pre-release indicator, will add the '--tag alpha' option
  checkRemoteVersion?: boolean // Check if the same version exists on the remote npm before publishing
  npmTag?: string              // NPM tag to publish
  cwd?: string                 // Working directory, defaults to process.cwd()
})

changelog

Description: Automatically generate Markdown-formatted changelogs based on standard Commit history.

Use cases: Useful for updating the CHANGELOG.md file independently without triggering the full release process.

Core Workflow: Traverse the Git commit history and format the output classified by predefined conventional commit rules (e.g., feat, fix).

CLI Commands:

Flags Reference:

Usage: vr changelog [flags...]

Flags:
      --release-count number          Release count  # default: 0
      --file string                   Changelog filename  # default: 'CHANGELOG.md'

Example:

# Generate changelogs for all history and output as CHANGELOG.md in the current directory
pnpm exec vr changelog

# Specify the generated changelog filename
pnpm exec vr changelog --file my-changelog.md
# Limit the range of release versions to generate changelogs for (0 means all)
pnpm exec vr changelog --release-count 0

Node API:

import { changelog } from '@varlet/release'

changelog({
  cwd?: string                 // Working directory, defaults to process.cwd()
  releaseCount?: number        // Number of recent releases to include in the log, defaults to 0 (all)
  file?: string                // Output changelog filename, defaults to 'CHANGELOG.md'
  showTypes?: string[]         // Commit types to display, defaults to ['feat', 'fix', 'perf', 'revert', 'refactor']
  outputUnreleased?: boolean   // Whether to output unreleased changes
  writerOpt?: object           // Specific configuration for conventional-changelog-writer
})

commit-lint

Description: Validate Git commit message formats.

Use cases: Used in combination with git hooks to enforce high-quality commit descriptions, ensuring the quality of the changelog.

Core Workflow: Read the commit file. If it matches the configured regex, the process continues; otherwise, it prints specific failure messages and aborts the commit.

CLI Commands:

Parameters Reference:

Usage: vr commit-lint <commit-message-path> [flags...]

Parameters:
  <commit-message-path>             Git commit message path (required)

Flags:
      --commit-message-re string      Validate the regex for commit message
      --error-message string          Error message displayed on validation failure
      --warning-message string        Warning message displayed on validation failure

Example:

# Check if the commit message at the given path is standard
pnpm exec vr commit-lint .git/COMMIT_EDITMSG

# Customize regex validation and prompt message
pnpm exec vr commit-lint .git/COMMIT_EDITMSG --commit-message-re "^feat: .*" --error-message "Commit validation failed"

It is recommended to integrate with simple-git-hooks or husky in package.json:

{
  "simple-git-hooks": {
    "commit-msg": "pnpm exec vr commit-lint $1"
  }
}

Node API:

import { commitLint } from '@varlet/release'

commitLint({
  commitMessagePath: string            // Required: Path to Git commit message file
  commitMessageRe?: string | RegExp    // Regex to validate the commit message format
  errorMessage?: string                // Error message printed upon failure
  warningMessage?: string              // Supplemental warning information printed upon failure
})

lockfile-check

Description: Detect and visually output in the console whether the lockfile of frontend dependencies has been modified, and automatically install dependencies by default to keep in sync.

Use cases: Recommended to use after Git operations such as pulling updates (git pull), switching branches (git checkout), or merging code. It helps detect if upstream dependency lockfiles (like pnpm-lock.yaml) have changed. If a change is detected, it will automatically invoke a package manager's installation command to synchronize the local environment with upstream instantly, preventing obscure bugs caused by outdated dependencies.

Core Workflow: Execute a Git diff comparing the project's lockfile (e.g. pnpm-lock.yaml or corresponding environment lockfile) from the original HEAD. Print its modification status in the console. Furthermore, trigger the package manager to reinstall dependencies to sync with upstream by default, or skip installation if directed by the command options.

CLI Commands:

Flags Reference:

Usage: vr lockfile-check [flags...]

Flags:
      --package-manager string        Package manager (npm, yarn, pnpm)  # default: 'pnpm'
      --skip-install                  Skip install dependencies when lockfile changed

Example:

# Check the synchronization status of the current lockfile and install dependencies if changed
pnpm exec vr lockfile-check

# Check current status but skip installation even if updates exist
pnpm exec vr lockfile-check --skip-install

# Specify other package managers for checking
pnpm exec vr lockfile-check --package-manager npm

It is also recommended to integrate with simple-git-hooks or husky in package.json (e.g. trigger checks and installations automatically during the post-merge or post-checkout hooks):

{
  "simple-git-hooks": {
    "post-merge": "pnpm exec vr lockfile-check"
  }
}

Node API:

import { lockfileCheck } from '@varlet/release'

lockfileCheck({
  packageManager?: 'npm' | 'yarn' | 'pnpm' // Choose package manager, defaults to 'pnpm'
  skipInstall?: boolean                    // Whether to skip installation if lockfile is out of sync
})

License

MIT