Skip to content

Validate and visualize dependencies. Your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.

License

Notifications You must be signed in to change notification settings

gplanetly/dependency-cruiser

Repository files navigation

Dependency cruiser Dependency cruiser

Visualize and validate javascript dependencies. With your rules. ES6, CommonJS, AMD, TypeScript.

Snazzy dot output to whet your appetite

Installation

Dependency cruiser works most comfortably when you install it globally.

npm install --global dependency-cruiser

Daphne's dependencies - a gentle introduction

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?

Basic usage

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)

Output formats

html

Write it to html with a dependency matrix instead:

dependency-cruise -T html -f dependencies.html src

csv

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.

dot

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

err

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.

Excluding modules from being cruised: --exclude

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

Validation

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 from src and node_modules
  • modules in src can not get stuff from test
  • stuff in node_modules can call anything, except stuff we wrote ourselves (in src, bin and lib)
  • 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 in node_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" }
        }]
}

License

MIT

Thanks

  • Marijn Haverbeke and other people who colaborated on acorn - the excelent javascript parser dependency-cruiser uses to infer dependencies.

build status coverage bitHound Overall Score bitHound Dependencies bitHound Dev Dependencies npm stable version total downloads on npm

About

Validate and visualize dependencies. Your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.

Resources

License

Code of conduct

Security policy

Rate limit · GitHub

Access has been restricted

You have triggered a rate limit.

Please wait a few minutes before you try again;
in some cases this may take up to an hour.

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 96.4%
  • HTML 1.4%
  • Handlebars 1.3%
  • TypeScript 0.4%
  • Vue 0.2%
  • CoffeeScript 0.2%
  • Other 0.1%