Visualize and validate javascript dependencies. With your rules. ES6, CommonJS, AMD, TypeScript.
Dependency cruiser works most comfortably when you install it globally.
npm install --global dependency-cruiser
Head over to Daphne's dependencies to get an overview of all the output formats. And how Daphne uses it all. And how she uses the awesome validation in her workflow. Go on. Read it. Or would you rather prefer continue the boring recount of a README written with reference doc in mind?
To dump all the dependencies in src
to into a dependency matrix you can
open in your browser:
dependency-cruise -T html -f deps.html src
Running with no parameters gets you help:
Usage: dependency-cruise [options] <directory-or-file>
Options:
-h, --help output usage information
-V, --version output the version number
-v, --validate [file] validate with rules from [file]
(default: .dependency-cruiser.json)
-f, --output-to <file> file to write output to; - for stdout (default: -)
-x, --exclude <regex> a regular expression for excluding modules
-M, --system <items> list of module systems (default: amd,cjs,es6)
-T, --output-type <type> output type - html|dot|err|json (default:json)
Write it to html with a dependency matrix instead:
dependency-cruise -T html -f dependencies.html src
If you supply csv
it will write the dependency matrix to a comma
separated file - so you can import it into a spreadsheet program
and analyze from there.
Supplying dot
as output type will make dependency-cruiser write
a GraphViz dot format directed graph. Typical use is in concert
with GraphViz dot:
dependency-cruise -x "^node_modules" -T dot src | dot -T svg > dependencygraph.svg
For use in build scripts, in combination with --validate
e.g.
dependency-cruise -T err --validate my-depcruise-rules.json src
This will:
- ... print nothing and exit with code 0 if dependency-cruiser didn't find any violations of the rules in .dependency-cruiser.json.
- ... print the violating dependencies if there is any. Moreover it will exit with exit code number of violations found in the same fasion linters and test tools do.
See the dependency-cruise target in the Makefile for a real world example.
If you don't want to see certain modules in your report (or not have them
validated), you can exclude them by passing a regular expression to the
--exclude
(short: -x
) option. E.g. to exclude node_modules
from being
scanned:
dependency-cruise -x "node_modules" -T html -f deps-without-node_modules.html src
Beacuse it's regular expressions, you can do more interesting stuff here as well. To exclude all modules with a file path starting with coverage, test or node_modules, you could do this:
dependency-cruise -x "^(coverage|test|node_modules)" -T html -f deps-without-stuffs.html src
Validates against a list of rules in a rules file. This defaults to a file
called .dependency-cruiser.json
, but you can specify your own rules file.
dependency-cruise -T err -x node_modules --validate my.rules.json
The file specifies a bunch of regular expressions pairs your dependencies should adhere to.
A simple validation configuration that forbids modules in src
to use stuff
in the test
folder and allows everything else:
{
"forbidden": [{
"from": {"path": "^src"},
"to": {"path": "^test"}
}]
}
You can optionally specify a name and an error severity ('error', 'warn' (the default) and 'info') with them that will appear in some reporters:
{
"forbidden": [{
"name": "no-src-to-test",
"severity": "error",
"from": {"path": "^src"},
"to": {"path": "^test"}
}]
}
A more elaborate configuration:
- modules in
src
can get stuff fromsrc
andnode_modules
- modules in
src
can not get stuff from test - stuff in
node_modules
can call anything, except stuff we wrote ourselves (insrc
,bin
andlib
) - modules with the pattern
no-deps-at-all-plz
in their name can't have dependencies to any module. - modules with the pattern
externalDependencyLess\.js
can't have dependencies to stuff innode_modules
. - modules can't have references to modules that can't be resolved
{
"forbidden": [{
"name": "not-to-test",
"comment": "don't allow dependencies from outside the test folder to test",
"severity": "error",
"from": { "pathNot": "^test" },
"to": { "path": "^test" }
},{
"name": "not-to-unresolvable",
"comment": "don't allow dependencies to modules that cannot be resolved (and probably don't exist on disk)",
"severity": "error",
"from": {},
"to": { "couldNotResolve": true }
},{
"name": "not-to-core-puny-os",
"comment": "allow dependencies on core modules, but not on 'punycode' (which has been deprecated) or 'os' (for no reason)",
"severity": "info",
"from": { },
"to": { "coreModule": true, "path": "^(punycode|os)$"}
}],
"allowed": [{
"from": { "path": "^(src|test)" },
"to": { "path": "^(src|node_modules)" }
}, {
"from": { "path": "^bin" },
"to": { "path": "^src/index\\.js" }
}, {
"from": { "path": "^src/index\\.js" },
"to": { "path": "^package\\.json$" }
}, {
"from": { "path": "^node_modules" },
"to": { "path": "^node_modules" }
}, {
"from": { "path": "^test" },
"to": { "path": "^test" }
}]
}
- Marijn Haverbeke and other people who colaborated on acorn - the excelent javascript parser dependency-cruiser uses to infer dependencies.