npm Deps Cleanup

npm Dependency Cleanup

Reduce JavaScript dependency footprint. Preserve the existing package manager, lockfile, workspace layout, and dependency range style unless there is a concrete reason to change them.

Workflow

1. Establish the baseline.
2. Remove unused direct dependencies.
3. Deduplicate direct dependency versions in monorepos.
4. Rank direct dependencies by transitive lockfile closure.
5. Use closure data to find low-risk minor/patch upgrades.
6. Use closure data to find trivial dependencies worth inlining.
7. Check e18e recommendations for replacements/removals.
8. Reinstall, verify, and report measured impact.

Package Manager Detection

Use the repo's existing package manager. Prefer explicit package metadata before lockfiles:

1. packageManager in the root package.json.
2. devEngines.packageManager.name in the root package.json.
3. Lockfile inference.

When devEngines.packageManager is present, use its name for npm, pnpm, Yarn, or Bun detection. Treat its version and onFail fields as policy signals, not as permission to change package managers.

Infer from lockfiles only when package metadata does not identify the package manager:

Use the matching command family:

Safety Rules

• Work in small batches so lockfile diffs remain reviewable.
• Never trust unused-dependency tools blindly; verify imports, config files, scripts, generated code hooks, framework conventions, plugin names, CLIs, and dynamic imports.
• You may write scripting and parsing to verify package.json and lockfile dependency accounts.
• Treat peerDependencies, optionalDependencies, package bin usage, test fixtures, and published package manifests as higher risk.
• Do not remove or inline dependencies used for security, parsing, crypto, Unicode, URL handling, date/time, i18n, or platform compatibility unless the replacement is proven equivalent.
• Do not change package managers, delete lockfiles, or rewrite workspace structure as part of cleanup.
• Treat package manager dedupe commands as potentially behavior-changing. They can alter selected transitive versions within allowed ranges, so inspect lockfile diffs and run focused verification before keeping the result.
• Measure before and after: direct dependency count, lockfile line count or entry count, package count, and estimated node_modules size when available.

Step 1: Baseline

Collect:

• All package.json files and workspace boundaries.
• Current package manager and lockfile.
• Direct dependency names by manifest section: dependencies, devDependencies, peerDependencies, optionalDependencies.
• Existing verification commands from scripts, CI, or repo docs.

Record baseline metrics before edits:

git status --short
wc -l <lockfile>

If node_modules is installed, also estimate installed footprint with platform-appropriate filesystem tools. Do not make footprint cleanup depend on node_modules being present; lockfile reductions are the primary metric.

Step 2: Remove Unused Direct Dependencies

Use a static analyzer as a starting point, not as proof. Good candidates include knip, depcheck, or repo-native tooling if already configured. Run them through the detected package manager's one-off executor when they are not installed.

For each candidate:

1. Search code, configs, package scripts, build tooling, tests, and docs for the package name and known import paths.
2. Check whether the dependency is required by a published package manifest, peer contract, plugin loader, CLI command, or dynamic require/import.
3. Remove only when no real usage remains.
4. Reinstall with the detected package manager and run focused verification.

If usage is only in a script or config, consider moving between dependencies and devDependencies instead of removing.

Step 3: Deduplicate Monorepo Direct Versions

In monorepos, look for the same direct dependency declared with multiple versions/ranges across package manifests. Use existing policy first: exact pins, caret ranges, catalog/protocol usage, workspace protocol, or central constraints.

Good approaches:

• Use syncpack list-mismatches or equivalent package-manager-neutral tooling for discovery.
• Standardize direct ranges when packages can share the same compatible version.
• Prefer manifest-level consistency before adding overrides/resolutions.
• Use overrides/resolutions only for transitive dependency convergence or security fixes, and document why.

After deduping, reinstall and inspect both manifest and lockfile diffs.

Then consider the package manager's native lockfile dedupe command: npm dedupe, pnpm dedupe, or yarn dedupe when available. Bun has no direct equivalent; run bun install and inspect whether the lockfile converges. Apply these commands carefully because they may change transitive dependency resolution and introduce breakage even without manifest edits.