🌜
🌞
depcheck

depcheck

v1.4.3

Check dependencies in your node module

npm install depcheck

README

depcheck

Depcheck is a tool for analyzing the dependencies in a project to see: how each dependency is used, which dependencies are useless, and which dependencies are missing from package.json.

Status

Build Status Financial Contributors on Open Collective Build status codecov.io

dependencies Status devDependencies Status

Installation

npm install -g depcheck

Or simply using npx which is a package runner bundled in npm:

$ npx depcheck

Notice: depcheck needs node.js >= 10.

Syntax Support

Depcheck not only recognizes the dependencies in JavaScript files, but also supports these syntaxes:

To get the syntax support by external dependency, please install the corresponding package explicitly. For example, for Typescript user, install depcheck with typescript package:

npm install -g depcheck typescript

Special

The special component is used to recognize the dependencies that are not generally used in the above syntax files. The following scenarios are supported by specials:

  • babel - Babel presets and plugins
  • bin - Dependencies used in npm commands, Travis scripts or other CI scripts
  • commitizen - Commitizen configuration adaptor
  • eslint - ESLint configuration presets, parsers and plugins
  • feross-standard - Feross standard format parser
  • gatsby - Gatsby configuration parser
  • gulp-load-plugins - Gulp-load-plugins lazy loaded plugins
  • husky - Husky configuration parser
  • istanbul - Istanbul nyc configuration extensions
  • jest - Jest properties in Jest Configuration
  • karma - Karma configuration frameworks, browsers, preprocessors and reporters
  • lint-staged - Lint-staged configuration parser
  • mocha - Mocha explicit required dependencies
  • prettier - Prettier configuration module
  • tslint - TSLint configuration presets, parsers and plugins
  • ttypescript - ttypescript transformers
  • webpack - Webpack loaders
  • serverless- Serverless plugins

The logic of a special is not perfect. There might be false alerts. If this happens, please open an issue for us.

Usage

depcheck [directory] [arguments]

The directory argument is the root directory of your project (where the package.json file is). If unspecified, defaults to current directory.

All of the arguments are optional:

--ignore-bin-package=[true|false]: A flag to indicate if depcheck ignores the packages containing bin entry. The default value is false.

--skip-missing=[true|false]: A flag to indicate if depcheck skips calculation of missing dependencies. The default value is false.

--json: Output results in JSON. When not specified, depcheck outputs in human friendly format.

--oneline: Output results as space separated string. Useful for copy/paste.

--ignores: A comma separated array containing package names to ignore. It can be glob expressions. Example, --ignores="eslint,babel-*".

--ignore-dirs: DEPRECATED, use ignore-patterns instead. A comma separated array containing directory names to ignore. Example, --ignore-dirs=dist,coverage.

--ignore-path: Path to a file with patterns describing files to ignore. Files must match the .gitignore spec. Example, --ignore-path=.eslintignore.

--ignore-patterns: Comma separated patterns describing files to ignore. Patterns must match the .gitignore spec. Example, --ignore-patterns=build/Release,dist,coverage,*.log.

--help: Show the help message.

--parsers, --detectors and --specials: These arguments are for advanced usage. They provide an easy way to customize the file parser and dependency detection. Check the pluggable design document for more information.

--config=[filename]: An external configuration file (see below).

Usage with a configuration file

Depcheck can be used with an rc configuration file. In order to do so, create a .depcheckrc file in your project's package.json folder, and set the CLI keys in YAML, JSON, and Javascript formats. For example, the CLI arguments --ignores="eslint,babel-*" --skip-missing=true would turn into:

.depcheckrc

ignores: ["eslint", "babel-*"]
skip-missing: true

Important: if provided CLI arguments conflict with configuration file ones, the CLI ones will take precedence over the rc file ones.

The rc configuration file can also contain the following extensions: .json, .yaml, .yml.

API

Similar options are provided to depcheck function for programming:

import depcheck from 'depcheck';

const options = {
  ignoreBinPackage: false, // ignore the packages with bin entry
  skipMissing: false, // skip calculation of missing dependencies
  ignorePatterns: [
    // files matching these patterns will be ignored
    'sandbox',
    'dist',
    'bower_components',
  ],
  ignoreMatches: [
    // ignore dependencies that matches these globs
    'grunt-*',
  ],
  parsers: {
    // the target parsers
    '**/*.js': depcheck.parser.es6,
    '**/*.jsx': depcheck.parser.jsx,
  },
  detectors: [
    // the target detectors
    depcheck.detector.requireCallExpression,
    depcheck.detector.importDeclaration,
  ],
  specials: [
    // the target special parsers
    depcheck.special.eslint,
    depcheck.special.webpack,
  ],
  package: {
    // may specify dependencies instead of parsing package.json
    dependencies: {
      lodash: '^4.17.15',
    },
    devDependencies: {
      eslint: '^6.6.0',
    },
    peerDependencies: {},
    optionalDependencies: {},
  },
};

depcheck('/path/to/your/project', options).then((unused) => {
  console.log(unused.dependencies); // an array containing the unused dependencies
  console.log(unused.devDependencies); // an array containing the unused devDependencies
  console.log(unused.missing); // a lookup containing the dependencies missing in `package.json` and where they are used
  console.log(unused.using); // a lookup indicating each dependency is used by which files
  console.log(unused.invalidFiles); // files that cannot access or parse
  console.log(unused.invalidDirs); // directories that cannot access
});

Example

The following example checks the dependencies under /path/to/my/project folder:

$> depcheck /path/to/my/project
Unused dependencies
* underscore
Unused devDependencies
* jasmine
Missing dependencies
* lodash

It figures out:

  • The dependency underscore is declared in the package.json file, but not used by any code.
  • The devDependency jasmine is declared in the package.json file, but not used by any code.
  • The dependency lodash is used somewhere in the code, but not declared in the package.json file.

Please note that, if a subfolder has a package.json file, it is considered another project and should be checked with another depcheck command.

The following example checks the same project, however, outputs as a JSON blob. Depcheck's JSON output is in one single line for easy pipe and computation. The json command after the pipe is a node.js program to beautify the output.

$> depcheck /path/to/my/project --json | json
{
  "dependencies": [
    "underscore"
  ],
  "devDependencies": [
    "jasmine"
  ],
  "missing": {
    "lodash": [
      "/path/to/my/project/file.using.lodash.js"
    ]
  },
  "using": {
    "react": [
      "/path/to/my/project/file.using.react.jsx",
      "/path/to/my/project/another.file.using.react.jsx"
    ],
    "lodash": [
      "/path/to/my/project/file.using.lodash.js"
    ]
  },
  "invalidFiles": {
    "/path/to/my/project/file.having.syntax.error.js": "SyntaxError: <call stack here>"
  },
  "invalidDirs": {
    "/path/to/my/project/folder/without/permission": "Error: EACCES, <call stack here>"
  }
}
  • The dependencies, devDependencies and missing properties have the same meanings in the previous example.
  • The using property is a lookup indicating each dependency is used by which files.
  • The value of missing and using lookup is an array. It means the dependency may be used by many files.
  • The invalidFiles property contains the files having syntax error or permission error. The value is the error details. However, only one error is stored in the lookup.
  • The invalidDirs property contains the directories having permission error. The value is the error details.

False Alert

Depcheck just walks through all files and tries to find the dependencies according to some predefined rules. However, the predefined rules may not be enough or may even be wrong.

There may be some cases in which a dependency is being used but is reported as unused, or a dependency is not used but is reported as missing. These are false alert situations.

If you find that depcheck is reporting a false alert, please open an issue with the following information to let us know:

  • The output from depcheck --json command. Beautified JSON is better.
  • Which dependencies are considered as false alert?
  • How are you using those dependencies, what do the files look like?

Changelog

We use the GitHub release page to manage changelog.

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute]. code contributor

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

individual

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

organization organization organization organization organization organization organization organization organization organization

License

MIT License.

Release Notes

1.4.3
By Djordje Lukic • Published on January 9, 2022

1.4.3 (2022-01-09)

Full Changelog

Fixed bugs:

  • Different results when running depcheck from npm install -g vs npx #689
  • Fails with Top-Level Await #671

Closed issues:

  • false alert on file src/server.js #655
  • Svelte Support #650
  • False positive: types-only dependencies #568

Merged pull requests:

1.4.2
By Djordje Lukic • Published on June 25, 2021

1.4.2 (2021-06-08)

Full Changelog

Fixed bugs:

  • Fails to parse serverless.yml if it contains certain CloudFormation syntax #639

Closed issues:

  • False positive: eslint overrides #570

Merged pull requests:

1.4.1
By Djordje Lukic • Published on May 11, 2021

1.4.1 (2021-05-11)

Full Changelog

Fixed bugs:

  • punycode being listed as unused, although the built in version is deprecated #628
  • Not working with Vue3 #610

Merged pull requests:

1.4.0
By Djordje Lukic • Published on February 16, 2021

1.4.0 (2021-02-16)

Full Changelog

Fixed bugs:

  • Not working with Vue3 #610
  • updating from 1.2.0 to 1.3.1 parsers glob stopped working #606
  • 非常差劲 导致我项目启动不了了!!!!误报非常的多 提issue 都不可能提的过来 #604
  • False positive: eslint-import-resolver-typescript #603
  • Depcheck Fails Incorrectly at "=" sign starting v1.3.0 #601
  • False positive in Next.js Config file: next.config.js #583

Closed issues:

  • Different output when invoking from shell script #617
  • How to disable a special when using the API? #614

Merged pull requests:

1.3.1
By Djordje Lukic • Published on November 9, 2020

1.3.1 (2020-11-09)

Full Changelog

BREAKING CHANGE

If you use depcheck as a library or have a configuration file please note that the parsers configuration changes slightly:

Before:

    parsers: {
        // the target parsers
        '*.js': depcheck.parser.jsx,
        '*.jsx': depcheck.parser.jsx,
    },

After:

    parsers: {
        // the target parsers
        '**/*.js': depcheck.parser.jsx,
        '**/*.jsx': depcheck.parser.jsx,
    },

Merged pull requests:

  • Fix extracting dependencies from webpack #602 (rumpl)
1.3.0
By Djordje Lukic • Published on November 9, 2020

1.3.0 (2020-11-09)

Full Changelog

BREAKING CHANGE

If you use depcheck as a library or have a configuration file please note that the parsers configuration changes slightly:

Before:

    parsers: {
        // the target parsers
        '*.js': depcheck.parser.jsx,
        '*.jsx': depcheck.parser.jsx,
    },

After:

    parsers: {
        // the target parsers
        '**/*.js': depcheck.parser.jsx,
        '**/*.jsx': depcheck.parser.jsx,
    },

Fixed bugs:

  • False positive: eslint import resolvers #571

Closed issues:

  • false alert for React 17 #591
  • false alert with typescript path aliases #590
  • Allow to define patterns against absolute file path (again) #589
  • Can't read property 'name' of undefined #579
  • Support .*ignore files #497

Merged pull requests:

  • Update dependencies #599 (rumpl)
  • Support webpack's oneOf in rules #598 (rumpl)
  • Fix eslint when eslint-plugin-import is used #597 (rumpl)
  • The error thrown is not always a YAML error #596 (rumpl)
  • Support parser patterns based on file paths #595 (rumpl)
  • Support react >= 17.0.0 that doesn't need to be imported #594 (rumpl)
  • Use the promise version of the api in the example #593 (rumpl)
  • Add option to run depcheck through npx #586 (elrumordelaluz)
  • fix(sass-parser): ignore local import in scss #581 (YonatanKra)
  • Improved webpack support #580 (cwillisf)
1.2.0
By Djordje Lukic • Published on August 12, 2020

1.2.0 (2020-08-12)

Full Changelog

Closed issues:

  • Sass 'use' syntax not working #576
  • depcheck should ignore depcheck by default #565
  • False unused dev dependencies report #560
  • False alert for eslint packages #554
  • Bug: specials are not working #551
  • depcheck should ignore hidden folders and files #543
  • ignore-patterns option from readme description is not supported in latest release #537
  • Option to exit without error code (when running via "npm run depcheck") #533
  • babelrc format #527
  • Support Gatsby plugins with resolve #525

Merged pull requests:

  • fix: now supports multi ignore in ignorePattern #578 (YonatanKra)
  • feat(sass parser): support @use and namespace syntax #577 (YonatanKra)
  • Add resolve and nested dependency check for Gatsby #573 (nagygergo)
  • fix: support eslint config that needs to be required #561 (znarf)
  • Feat: Special for serverless config #559 (mzl-md)
  • Add node 14.x to the matrix #557 (rumpl)
  • Try to parse JSON5 babelrc files #556 (rumpl)
  • chore: update all dependencies (July 2020) #555 (znarf)
1.0.0
By Djordje Lukic • Published on July 5, 2020

1.0.0 (2020-05-14)

Full Changelog

Closed issues:

  • Error when running from script #531
  • Missing Changelog for 0.9.2 #521
  • Depcheck should only process files that are relevant to depcheck #420
  • False positive when using inline Webpack loader #236
  • Dependencies out of date #273
  • Add support for @types declaration packages #163
  • Improvements for CI use #162

Merged pull requests:

0.9.2
By Djordje Lukic • Published on January 30, 2020

Full Changelog

Closed issues:

  • Use Cosmiconfig #516
  • Feature: add special parser for Istanbul.js #508
  • New mocha configuration file not seen #507
  • False positive with @types/mocha #504
  • Error: ENFILE: file table overflow (macOS) #501
  • eslint: dependency wrongly mark as unused #500
  • special/eslint: bad calculation of preset dependencies #476
  • Load ignore rules from a lines separated file #409
  • Improvements for CI use #162

Merged pull requests:

  • Review special documentation #515 (sveyret)
  • Add Istanbul special parser #514 (sveyret)
  • Refactor: read content only when needed #513 (znarf)
  • Add debug package and messages to the project #512 (znarf)
  • Support for more decorators #511 (micky2be)
  • Improve recursive work of eslint configuration check #506 (sveyret)
  • Improvements for mocha #505 (sveyret)
  • Support webpack styleguidist configuration #503 (znarf)
  • Use a single promise to read a given file #502 (znarf)
  • Support for next.js webpack configuration #496 (znarf)
  • Rename 'linters' and fix babel config file detection #495 (znarf)
  • Suppress unnecessary fileContent #494 (znarf)
  • Update travis commands and reference #493 (znarf)
  • Add eslint-plugin-mocha and lint test directory #492 (znarf)
  • Better prettier configuration #490 (znarf)
  • Remove remaining dev option #489 (znarf)
  • chore: remove editorconfig file #488 (rumpl)
  • Update babel target to node 10, use prettier plugin #487 (rumpl)
  • chore(deps): Update all dependencies to latest #486 (rumpl)
  • Do not calculate expensive dep differences when skipMissing is active #485 (dword-design)
  • Adjust babel special to eslint implementation #484 (dword-design)
  • Add deps parameter to detectors #482 (dword-design)
  • Activating Open Collective #481 (monkeywithacupcake)
  • Document and provide types for the API's package option #479 (edsrzf)
  • Try to load eslint.js modules without a module.exports wrapper #478 (rjatkins)
  • special/eslint: corrections on dependencies resolver #477 (sveyret)
  • chore: add changelog file #475 (rumpl)
  • Support loading configuration from a config file. #408 (Urik)
0.9.1
By Djordje Lukic • Published on November 8, 2019

Features

  • better support for workspaces #473
  • support for prettier shared configuration #474
  • support for typescript webpack configuration #459
  • added support for ttypescript #469
  • typescript types! #458
  • added support for lint-staged #456
  • added support for husky #453
  • added support for babel.config.js

Bugfixes

  • consitent exit code #465
  • fixed false positive when using plugin:prettier/recommended #464
  • fixed false positive when using tslint-plugin-prettier #457

Big thanks to @VincentLanglet and @sveyret

I almost made this 1.0.0 but it will be for the next.

General

License
MIT
Typescript Types
Built-in
Tree-shakeable
No

Popularity

GitHub Stargazers
3,423
Community Interest
3,023
Number of Forks
195

Maintenance

Commits
10/219/2209
Last Commit
Open Issues
28
Closed Issues
354
Open Pull Requests
12
Closed Pull Requests
66

Versions

Versions Released
10/219/2202
Latest Version Released
Jan 9, 2022
Current Tags
latest1.4.3
next0.7.0-alpha.1

Contributors

lijunle
lijunle
Commits: 418
rumpl
rumpl
Commits: 99
znarf
znarf
Commits: 31
sveyret
sveyret
Commits: 19
YonatanKra
YonatanKra
Commits: 16
dword-design
dword-design
Commits: 15
rjatkins
rjatkins
Commits: 12
43081j
43081j
Commits: 12
Urik
Urik
Commits: 12
mnkhouri
mnkhouri
Commits: 12
dylang
dylang
Commits: 11
sudo-suhas
sudo-suhas
Commits: 8
woodb
woodb
Commits: 6
winniehell
winniehell
Commits: 5
LinusU
LinusU
Commits: 5