Release Doctor

Release Doctor is a lightweight command line utility for npm package maintainers. It scans a package or npm workspace before release and reports issues that commonly break npm publish, CI verification, or downstream installs.

Install

npm install --save-dev release-doctor

Run it from any package directory:

npx release-doctor .

Or add a project script:

{
  "scripts": {
    "release:doctor": "release-doctor --strict ."
  }
}

For CI, use strict mode so warnings fail the job:

npx release-doctor --strict .

You can also run without installing:

npm exec release-doctor -- .

GitHub Actions

name: Release checks

on:
  pull_request:
  push:
    branches: [main]

jobs:
  release-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx release-doctor --strict .

What It Checks

Release Doctor focuses on static checks that are safe to run before dependencies are installed:

• npm manifest correctness: package name, version, private packages, license, engines, repository metadata, package manager pinning, scoped package publish access.
• Publish surface: main, exports, types, bin, missing entrypoint files, CLI shebangs, executable bits, and files allowlist coverage.
• Dependency hazards: conflicting dependency ranges across dependency sections, self dependencies, wildcard ranges, local path dependencies, workspace protocol leaks, peer dependencies missing from local test installs, and stale peer metadata.
• Release process: missing or placeholder test scripts, deprecated prepublish, dist entrypoints without build hooks, missing README, license file, and changelog.
• Reproducibility: missing or stale lockfiles and package-manager mismatches.
• CI readiness: missing GitHub Actions workflows, missing install/test steps, publish workflows without checks, missing publish authentication, and Corepack setup for pnpm or Yarn.
• Workspace drift: npm workspace package discovery and dependency range drift across packages.
• Security hygiene: committed literal npm tokens in .npmrc.

Example Output

Release Doctor FAIL for .
1 package(s), 2 error(s), 1 warning(s), 0 info

.
  [error] ENTRYPOINT_MISSING_FILE: Declared entrypoint file is missing (package.json)
    main points to ./dist/index.js, but that file does not exist.
    Fix: Build the file before publishing or update package.json to the correct path.

CLI

release-doctor [project-path] [options]

Options:
  --json             Print a machine-readable JSON report.
  --strict           Exit non-zero when warnings are present.
  --no-ci            Skip CI and .npmrc checks.
  --no-workspaces    Only inspect the nearest package.json.
  -v, --version      Print the CLI version.
  -h, --help         Show help.

Exit code 0 means no release blockers were detected. Exit code 1 means errors were found, or warnings were found in --strict mode. Exit code 2 means invalid CLI usage or an unexpected runtime failure.

JSON Reports

Use --json when another tool needs to consume the result:

npx release-doctor --json .

The JSON output includes package summaries, issue counts, severity, category, stable issue codes, recommendations, and evidence when available.

Usage Guide

See docs/USAGE.md for local development workflows, CI examples, JSON consumption, and troubleshooting.

See docs/ISSUE_CODES.md for the stable diagnostic codes emitted in human-readable and JSON reports.

Development

npm ci
npm test
npm run check

The package intentionally has no runtime dependencies.

Releasing

Maintainers can publish from a GitHub release. The release workflow runs npm ci, npm run check, and npm publish --provenance.

Manual releases are guarded by prepublishOnly, which runs the full check suite before npm publish.

See docs/RELEASE.md for the release checklist, changelog format, and npm publishing options.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. Please keep new checks deterministic and avoid executing target package scripts unless the user explicitly opts in.

Support

See SUPPORT.md for where to ask usage questions and how to report bugs.

Security

Please report security issues privately through GitHub security advisories when available, or by contacting the maintainer listed on npm.