Skip to content

Wrangling Large Projects with Dependency Graphs

by David Yates

Whenever I’m working on a new project, it can become confusing trying to figure out exactly what dependencies a project has - or more accurately - what files call out to other files.

In my journey to find a better way of visualizing this, I came across dependency cruiser. This amazing little tool will crawl a codebase for you and spit out a lovely picture showing you exactly what files are linked to others.


To use dependency-cruiser, you’ll need to install it as a local package in your project:

npm install --save-dev dependency-cruiser

Alternatively, you can install it globally if you’d like to use it for multiple projects or system-wide:

npm install -g dependency-cruiser

Before you use it, you’ll also need to install GraphViz.

Generating a Dependency Graph

Assuming your project is in the src directory, you can browse to your project’s root and run the following command to generate the dependency graph:

depcruise --exclude "^node_modules" --output-type dot src | dot -T svg > dependencygraph.svg

This command will save the dependency graph as an SVG file called dependencygraph.svg in your project’s root.

Cool stuff.

Handling Complexity

Obviously, the bigger the project, the more complicated the diagram will become. To handle that, you can set the maxDepth and a bunch of other options, or even write your own project-specific rule - the options are endless!

CI Pipeline Integration

One very useful thing you can do is make dependency-cruiser part of your CI pipeline by adding it as a script to your package.json:

  "scripts": {
    "build:deptree": "depcruise --exclude '^node_modules' --output-type dot src | dot -T svg > dependencygraph.svg"

Now you can run npm run build:deptree to generate the dependency graph during your CI build process.

Happy visualizing!

All Posts