pkg-guard

npm package publishing hygiene

pkg-guard

Find broken entrypoints. Catch bad tarballs and failed consumer installs. Check workspaces, release workflows, and editor-ready diagnostics before publish.

Install View source
0 runtime services
3 contract layers
2 diagnostics integration paths

Checks

A practical preflight for package releases.

`pkg-guard check` inspects the files and metadata that consumers actually rely on across three modes: fast source-tree analysis, default tarball-aware validation, and optional installed consumer smoke checks.

Manifest

Package metadata that resolves cleanly.

Validate names, versions, licenses, repository links, package managers, scoped publish access, and publish-oriented fields.

Entrypoints

Imports and binaries that exist.

Check `main`, `types`, `exports`, and `bin` targets, including common export patterns, before a consumer finds the broken path.

Packlist

The tarball, not the wishful version.

Use npm pack inspection to detect missing files, junk artifacts, and sensitive files in publish output.

Consumer smoke

The installed package has to resolve.

Opt into tarball install checks that verify runtime resolution, bin layout, and TypeScript declarations without executing package code.

Intent

Checks shaped to the package.

Infer CLI, TypeScript library, or generic intent so package-specific findings stay useful and suppressible.

Workspaces

Publishable packages checked together.

Run across npm and pnpm workspace layouts, skip private packages by default, and target one package by name or path.

CI

Human, JSON, SARIF, and diagnostics output.

Use concise local output, stable finding JSON, SARIF for code scanning, or diagnostics JSON for integration tooling.

Diagnostics

Findings ready for tool integrations.

Use diagnostics JSON or the experimental analysis API for package and workspace diagnostics with layer, cost, and source range metadata.

Release

Publishing workflows that match npm expectations.

Check trusted publishing posture, validation steps, Node and npm versions, and scoped package publish access before release.

Workspaces

One pass across every package you publish.

Run `pkg-guard check --workspaces` from the repository root to audit publishable workspace packages. Add `--mode smoke` when CI should install each package's tarball in isolation. Private packages are skipped unless explicitly included, and package-local config stays package-local.

API

Diagnostics before the release gate.

`pkg-guard check --format diagnostics-json` and `pkg-guard/experimental/analysis` return package and workspace diagnostics for integrations that need findings before CI. Fast mode skips npm pack and smoke work for editor-style loops, while default and smoke modes match release validation needs.

Workflow

Built for the moment before publish.

Keep `pkg-guard` close to the release path: run `--mode fast` locally for quick source diagnostics, then run default or smoke mode in CI after the package build and before `npm publish`.

$ npx pkg-guard check --workspaces --format diagnostics-json --mode smoke
  1. manifest metadata
  2. entrypoint targets
  3. packed package contents
  4. installed runtime resolution
  5. bin and declaration smoke
  6. workspace and release workflow posture

Install

One dev dependency, one CI gate.

npm install -D pkg-guard
npx pkg-guard check --workspaces
npx pkg-guard check --workspaces --format diagnostics-json --mode fast
npx pkg-guard fix --dry-run
npx pkg-guard init --dry-run
npx pkg-guard init-release