pkg-clean

Find and remove unused dependencies from your Node.js project

A minimal, fast CLI tool that scans your project for unused npm dependencies. Identifies unused packages, duplicates, and deprecated packages in seconds.

Features

• Scan for unused dependencies - finds packages in package.json that aren't imported anywhere
• Detect duplicates - spots packages listed in both dependencies and devDependencies
• Check deprecation status - warns about deprecated packages via NPM registry
• Safe by default - uses dry-run mode, only removes with --remove flag
• Fast - scans large projects in under a second
• Minimal & slick CLI - beautiful colored output with clear formatting

Installation

npm install -g pkg-clean

Or run directly without installing:

npx pkg-clean

Usage

Scan current project

pkg-clean

Output:

◆ pkg-clean
→ Scanning files...
✓ Found 12 imports
→ Analyzing dependencies...
→ Checking for deprecated packages...

◆ Report
◆ Unused dependencies (3)
  ● @types/jest
  ● @types/node
  ● ts-jest

→ Run with --remove to clean up unused dependencies

Remove unused dependencies

pkg-clean --remove

This will:

1. Remove unused packages from your package.json
2. Show you which packages were removed
3. Suggest running npm install

Show verbose output

pkg-clean --verbose

Displays detailed information about all imports, dependencies, and analysis results.

Keep specific packages

pkg-clean --keep lodash react

Excludes specified packages from removal (even if unused).

Scan a different directory

pkg-clean /path/to/project

Combine options

pkg-clean /path/to/project --remove --verbose --keep lodash

Dry-run to preview changes

pkg-clean --remove --verbose

Output (without --remove):

→ Run with --remove to clean up unused dependencies

This allows you to review what would be removed before applying changes.

Use with npm scripts

Add to your package.json:

{
  "scripts": {
    "clean:deps": "pkg-clean",
    "clean:deps:remove": "pkg-clean --remove",
    "clean:deps:check": "pkg-clean --verbose"
  }
}

Then run:

npm run clean:deps:check    # Preview unused dependencies
npm run clean:deps:remove   # Remove unused dependencies

CI/CD Integration

Check for unused dependencies in your CI pipeline:

# Fail if unused dependencies are found
pkg-clean --verbose

Exit code will be non-zero if unused dependencies are detected (useful for CI gates).

Configuration

Create a pkg-clean.config.json file in your project root to set default packages to keep:

{
  "keep": ["lodash", "moment"]
}

Example configurations:

For a React project:

{
  "keep": ["react", "react-dom", "react-router-dom"]
}

For a monorepo:

{
  "keep": ["@company/shared-utils", "@company/types"]
}

For a library with peer dependencies:

{
  "keep": ["tslib", "@types/node"]
}

How it works

1. Scans all .js, .ts, .jsx, .tsx files in your project
2. Extracts import/require statements using regex patterns
3. Compares found imports against package.json entries
4. Reports unused, duplicates, and deprecated packages
5. Removes from package.json (if --remove flag is used)

What it detects

✅ Detects

• import statements: import foo from 'bar'
• require() calls: require('foo')
• Scoped packages: @babel/core
• Nested imports: lodash/map → detects lodash
• Both dependencies and devDependencies
• Duplicate packages in both sections
• Deprecated packages from NPM registry

⚠️ Limitations

• Doesn't analyze dynamic imports like require(variable)
• Doesn't check .json, .html, or config files
• Doesn't evaluate webpack/babel configs
• Doesn't track indirect dependencies

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests in watch mode
npm test:watch

# Run locally
node dist/cli.js

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © 2026