dependency-cruiser

What is dependency-cruiser?

dependency-cruiser is a tool to analyze and visualize the dependencies in your JavaScript and TypeScript projects. It helps you understand the structure of your codebase, identify potential issues, and enforce architectural rules.

What are dependency-cruiser's main functionalities?

Dependency Graph Generation

Generates a dependency graph for the specified source directory. This helps in visualizing the dependencies between different modules in your project.

const depCruiser = require('dependency-cruiser');
const result = depCruiser.cruise(['src']);
console.log(result.output);

Enforcing Architectural Rules

Allows you to define and enforce architectural rules, such as preventing circular dependencies. This helps maintain a clean and manageable codebase.

const depCruiser = require('dependency-cruiser');
const config = {
  forbidden: [
    {
      name: 'no-circular',
      severity: 'error',
      comment: 'Circular dependencies are not allowed',
      from: {},
      to: {
        circular: true
      }
    }
  ]
};
const result = depCruiser.cruise(['src'], config);
console.log(result.output);

Reporting

Generates reports in various formats (e.g., JSON, HTML) to help you analyze the dependency structure and identify potential issues.

const depCruiser = require('dependency-cruiser');
const result = depCruiser.cruise(['src'], {}, { outputType: 'json' });
console.log(JSON.stringify(result.output, null, 2));

Other packages similar to dependency-cruiser

madge

Madge is a JavaScript library that visualizes the module dependency graph of your project. It can detect circular dependencies and generate visual graphs. Compared to dependency-cruiser, Madge is more focused on visualization and less on enforcing architectural rules.

depcheck

Depcheck is a tool that helps you find unused dependencies in your project. While it doesn't provide the same level of dependency graph visualization as dependency-cruiser, it is useful for cleaning up your package.json file by identifying dependencies that are no longer in use.

webpack-bundle-analyzer

Webpack Bundle Analyzer is a tool that visualizes the size of webpack output files with an interactive zoomable treemap. It is more focused on analyzing the size and composition of your webpack bundles rather than the dependency structure of your source code.

README

Dependency cruiser

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

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.