pkg-guard

Guard npm package manifests, entry points, and release workflows before publishing.

pkg-guard is a TypeScript CLI for npm package publishing hygiene. It audits package metadata, declared entry points, packed package contents, TypeScript declaration settings, GitHub Actions npm publishing workflows, conservative dependency risks, publishable workspace packages, and editor-ready diagnostics through an experimental analysis API.

Product site: https://jeremyaaron.github.io/pkg-guard/

Install

npm install -D pkg-guard

Usage

npx pkg-guard check
npx pkg-guard check --format json
npx pkg-guard check --format diagnostics-json --mode fast
npx pkg-guard check --format sarif
npx pkg-guard fix --dry-run
npx pkg-guard init --dry-run
npx pkg-guard init-release

check is read-only and exits with 1 when errors are found. Warnings do not fail the command unless promoted through strict config.

Use --mode fast, --mode default, or --mode smoke to choose check cost. fast runs source-tree analysis only and skips npm pack and consumer smoke checks. default matches normal pkg-guard check behavior, including npm pack inspection. smoke runs default analysis plus consumer smoke checks. The existing --consumer-smoke flag remains supported as a readable alias for --mode smoke.

fix applies only conservative package.json metadata fixes such as packageManager, repository metadata, types, files, scoped package access, inferred Node engines, and low-risk sideEffects. Use --dry-run to preview changes.

init adds a local pkg:check script and conservative pkgGuard config when it can infer package intent safely. Use --dry-run to preview changes.

init-release creates .github/workflows/release.yml for npm trusted publishing and refuses to overwrite an existing release workflow.

Workspaces

Run checks across publishable workspace packages:

npx pkg-guard check --workspaces
npx pkg-guard check --workspaces --format diagnostics-json --mode fast
npx pkg-guard check --workspaces --format sarif > pkg-guard.sarif
npx pkg-guard fix --workspaces --dry-run
npx pkg-guard init --workspaces

Select one package by package name or repository-relative path:

npx pkg-guard check --workspace @scope/pkg
npx pkg-guard fix --workspace packages/pkg

Workspace mode reads package.json workspaces, package.json workspaces.packages, and pnpm-workspace.yaml packages. It skips packages with private: true by default. Add --include-private to include private packages and --include-root to include the workspace root when using --workspaces; a private root also needs --include-private.

Diagnostics JSON

--format json is the stable release-gate report format built around findings. It remains compatible with earlier versions and does not include diagnostic-only fields.

--format diagnostics-json is the tooling-oriented format for editors, pre-commit hooks, wrappers, and non-TypeScript integrations:

npx pkg-guard check --format diagnostics-json
npx pkg-guard check --format diagnostics-json --mode fast
npx pkg-guard check --workspaces --format diagnostics-json --mode smoke

Diagnostics include source, layer, cost, and optional location.range metadata. Ranges are zero-based: line 0 is the first line, column 0 is the first UTF-16 code unit in the line, and offset is a zero-based UTF-16 code unit offset when present.

See diagnostics CLI output.

Configuration

Optional config lives in package.json:

{
  "pkgGuard": {
    "preset": "typescript-library",
    "ignore": ["dependencies.runtime-in-dev"],
    "strict": ["manifest.files-missing"]
  }
}

pkg-guard infers cli, typescript-library, or generic from package metadata. Configure preset when the inferred intent is too broad or too narrow for the package.

In workspace mode, each package uses its own package.json pkgGuard config. Root config is not silently inherited by workspace packages.

See configuration and check IDs.

Experimental Analysis API

Tooling integrations can import diagnostic analysis from the experimental subpath:

import { analyzePackageForDiagnostics } from "pkg-guard/experimental/analysis";

const result = await analyzePackageForDiagnostics({
  cwd: process.cwd(),
  mode: "fast"
});

The API supports fast, default, and smoke modes, returns diagnostics with source, layer, cost, and optional zero-based source ranges, and includes a workspace variant for package families. The subpath is documented and tested, but it may change in minor releases before 1.0.0.

See experimental analysis API.

Docs

• Diagnostics CLI output
• Experimental analysis API
• Check IDs
• Configuration
• Release workflow generation
• Publishing
• Examples

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
node dist/cli/index.js check