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
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:
- JavaScript (ES5, ES6 and ES7)
- React JSX
- CoffeeScript
- Typescript (with
typescript
dependency) - SASS and SCSS (with
node-sass
dependency) - Vue.js (with
@vue/compiler-sfc
dependency)
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 pluginsbin
- Dependencies used in npm commands, Travis scripts or other CI scriptscommitizen
- Commitizen configuration adaptoreslint
- ESLint configuration presets, parsers and pluginsfeross-standard
- Feross standard format parsergatsby
- Gatsby configuration parsergulp-load-plugins
- Gulp-load-plugins lazy loaded pluginshusky
- Husky configuration parseristanbul
- Istanbul nyc configuration extensionsjest
- Jest properties in Jest Configurationkarma
- Karma configuration frameworks, browsers, preprocessors and reporterslint-staged
- Lint-staged configuration parsermocha
- Mocha explicit required dependenciesprettier
- Prettier configuration moduletslint
- TSLint configuration presets, parsers and pluginsttypescript
- ttypescript transformerswebpack
- Webpack loadersserverless
- 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: