Dependency cruiser

Validate and visualise dependencies. With your rules. JavaScript. TypeScript. CoffeeScript. ES6, CommonJS, AMD.

This runs through the dependencies in any JavaScript, TypeScript, LiveScript or CoffeeScript project and ...

• ... validates them against (your own) rules
• ... reports violated rules
  • in text (for your builds)
  • in graphics (for your eyeballs)

As a side effect it can generate dependency graphs in various output formats including cool visualizations you can stick on the wall to impress your grandma.

npm install --save-dev dependency-cruiser
# or
yarn add -D dependency-cruiser
pnpm add -D dependency-cruiser

npx depcruise --init

This will look around in your environment a bit, ask you some questions and create a .dependency-cruiser.js configuration file attuned to your project¹².

To create a graph of the dependencies in your src folder, you'd run dependency cruiser with output type dot and run GraphViz dot³ on the result. In a one liner:

npx depcruise src --include-only "^src" --output-type dot | dot -T svg > dependency-graph.svg

dependency-cruiser v12 and older: add --config option

While not necessary from dependency-cruiser v13 and later, in v12 and older you'll have to pass the --config option to make it find the .dependency-cruiser.js configuration file:

npx depcruise src --include-only "^src" --config --output-type dot | dot -T svg > dependency-graph.svg

• You can read more about what you can do with --include-only and other command line options in the command line interface documentation.
• Real world samples contains dependency cruises of some of the most used projects on npm.
• If your grandma is more into formats like mermaid, json, csv, html or plain text we've got her covered as well.

When you ran depcruise --init above, the command also added some rules to .dependency-cruiser.js that make sense in most projects, like detecting circular dependencies, dependencies missing in package.json, orphans, and production code relying on dev- or optionalDependencies.

Start adding your own rules by tweaking that file.

Sample rule:

{
  "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" }
    }
  ]
}

• To read more about writing rules check the writing rules tutorial or the rules reference

npx depcruise src

dependency-cruiser v12 and older: add --config option

While not necessary from dependency-cruiser v13, in v12 and older you'll have to pass the --config option to make it find the .dependency-cruiser.js configuration file:

npx depcruise --config .dependency-cruiser.js src

This will validate against your rules and shows any violations in an eslint-like format:

There's more ways to report validations; in a graph (like the one on top of this readme) or in an self-containing html file.

• Read more about the err, dot, csv and html reporters in the command line interface documentation.
• dependency-cruiser uses itself to check on itself in its own build process; see the depcruise script in the package.json

You've come to the right place :-) :

• Usage
  • Command line reference
  • Writing rules
  • Rules reference
  • Options reference
  • FAQ
• Hacking on dependency-cruiser
  • API
  • Output format
  • Adding other output formats
  • Adding support for other alt-js languages
• Other things
  • Road map
  • Contact
  • Real world show cases
  • TypeScript, CoffeeScript and LiveScript support
  • Support for .jsx, .tsx, .csx/ .cjsx, .vue and .svelte
  • Webpack alias/ modules support

MIT

• Marijn Haverbeke and other people who collaborated on acorn - the excellent JavaScript parser dependency-cruiser uses to infer dependencies.
• Katerina Limpitsouni of unDraw for the ollie in dependency-cruiser's social media image.
• All members of the open source community who have been kind enough to raise issues, ask questions and make pull requests to get dependency-cruiser to be a better tool.

Made with 🤘 in Holland.