knip-guard

Guard your codebase from new dead code issues detected by Knip.

knip-guard adds a minimal baseline/snapshot mechanism so large or legacy repositories can adopt Knip without blocking progress or hiding existing issues from reports, but rather as a mechanism to accept and progressively improve and accept new issues if needed, promoting ownership and visibility. You keep all existing issues for now — but no new issues can be introduced.

🚀 Why knip-guard?

Knip is excellent at discovering:

• unused files
• unused exports
• unused dependencies
• unresolved imports
• dead enum/class members
• and more…

But if you already have hundreds of issues, enabling Knip in CI immediately will break every PR.

knip-guard solves this by:

• creating a baseline (snapshot of current issues)
• allowing those issues to exist temporarily
• failing CI only when new issues appear
• letting teams clean old issues gradually and safely

This is the same model used by tools like SonarQube, ESLint’s --init baseline mode, and static analyzers.

❗ How is this different from Knip’s ignore functionality?

Knip provides an ignore config, but it is not the same thing.

ignore is static

You manually list files/paths/symbols to ignore forever.

Problems:

• It does not distinguish between old accepted issues and new regressions.
• It grows stale as code changes.
• It must be manually curated.
• If you ignore everything, you lose all value from Knip.

knip-guard is dynamic

It maintains a snapshot of all current issues and blocks only newly introduced ones.

Advantages:

• Zero manual maintenance.
• Old issues tolerated; new ones blocked.
• Ideal for large monorepos full of legacy dead code.
• Baseline updates are intentional and simple (knip-guard accept).

In short: ignore hides issues. knip-guard prevents regressions.

📦 Installation

npm install --save-dev knip-guard

Usage

Install as a dev dependency:

npm install --save-dev knip-guard

Initialize a baseline (run this once in a clean state):

npx knip-guard init --command "npm run knip"

Check in CI (exit code 1 when new issues are introduced):

npx knip-guard check --command "npm run knip"

Accept new issues (after review) and update baseline:

npx knip-guard accept --command "npm run knip"

CLI options:

• -b, --baseline Path to baseline file (default: .knip-baseline.json)
• -r, --report Path to existing Knip JSON report (otherwise run knip)
• -c, --command Command to run knip (default: "npx knip")
• -h, --help Show help

Build, test & publish

Build (generate JS + types in dist/):

npm run build

Run tests:

npm test

Prepare/publish:

• The package has a prepare and prepublishOnly script that runs the build.
• Before publishing, ensure dist/ contains the compiled files and the CLI (dist/cli.js) includes the shebang line.