dependencies2graph

Having a visual representation of your project structure is a great benefit. Humans are visual beings and our brain is really great at recognizing patterns and structures. This can be utilised at getting new developers up to speed in a short time. It also helps all developers building a cleaner application, because of a better understanding of the whole project.

Getting started

Install dependencies2graph (prefer global). This project uses the output from another tool called dependency-cruiser. You need it as well, so install them together

npm install --global dependencies2graph dependency-cruiser

If you're using TypeScript make sure that you have the TypeScript compiler installed as well

npm install -g typescript

Create a JSON file of your dependencies with dependency-cruiser and than start the interactive viewer or create your graphs via dependencies2graph cli. When using TypeScript dependency-cruiser by default ignores compile time dependencies like interfaces and types. To include these compile time dependencies add the --ts-pre-compilation-deps command line flag to call of dependency-cruiser.

A typical usage for TypeScript and ignoring everything in your node_modules folder is the following:

dependency-cruiser -T json --exclude "^node_modules" -f deps.json <path-to-source> --ts-pre-compilation-deps
dependencies2graph deps.json

For a one-off views you can simply pipe the output from dependency-cruiser direct to dependencies2graph

dependency-cruiser -T json --exclude "^node_modules" <path-to-source> | dependencies2graph

To get a svg with an overview of a typical Angular application you can call

dependencies2graph generate --input deps.json --out overview.svg --filter src/app

CLI

start interactive graph viewer

$ dependencies2graph viewer [dependency-file]
# or read from stdin 
$ cat dependency.json | dependencies2graph viewer

When you hover a node or edge on the interactive graph all connected dependencies and dependants are highlighted. The light blue dependencies and dependants are direct dependencies and the darker blue are transient one.

generate images

$ dependencies2graph generate
 
Optionen:
  --version                    Version anzeigen                        [boolean]
  --help                       Hilfe anzeigen                          [boolean]
  -i, --input                  dependency-cruiser JSON file, if omitted read
                               from stdin                               [string]
  -f, --filter                 path for the dependency subgraph
                                                          [string] [default: ""]
  -d, --depth                  number of child folders to show(0 for infinite)
                                                           [number] [default: 1]
  -D, --external-depth         number of child folders for external dependencies
                                                           [number] [default: 1]
  -e, --external-dependencies  flag to show dependencies which point outside of
                               <filter>              [boolean] [default: false]
  -F, --external-filter        filter path for external dependencies and
                               dependents                               [string]
  -E, --external-dependents    flag to show dependents which point inside of
                               <filter>              [boolean] [default: false]
  -C, --connected-components   mark all connected components of the dependency
                               tree as circular      [boolean] [default: false]
  -o, --out                    output file           [string] [default: stdout]
  -t, --target                 output format
                 [string] [choices: "svg", "dot", "raw"] [default: "svg"]
  --engine                     Graphviz engine (responsible for graph layout)
      [string] [choices: "dot", "circo", "fdp", "neato", "osage", "twopi"]
                                                               [default: "dot"]

-i, --input (required):

JSON file generated by dependency-cruiser. Dependency-graph supports both formats from dependency-cruiser version <=3 and the new version 4.0.0.

-f, --filter (required):

Regex for file path, that should be included in the graph, e.g. --filter src/app

-o, --out

Output file. If not specified the output is printed to stdout.

-d, --depth:

Number of the level of directories that should be expanded. If the depth of the dependencies is bigger than the parameter they are collapsed in a folder node in the graph.

-e, --external-dependencies

Flag that indicates, that external dependencies should also be shown in the output graph. By definition a dependency is external if the source path of the file does not match the filter parameter.

-D, --external-depth

-t, --target

Output target format.

• svg: graph as svg vector file.
• dot: graph as dot file to be consumed by Graphviz. The svg target uses viz.js - an JavaScript port of Graphviz - to generate the svg. Here is a memory constrain for big graphs. In this cases Graphviz can be used directly with the dot source.
• raw: JSON of the interal graph representation. Should mainly be used for debugging purpose

-E, --engine

The Grapviz engine to use when generating a svg file. The engine is responsible for the layout of the resulting graph. By default the 'dot' engine is used and it should not be necessary to modify this parameter. For more information consult the Graphviz documentation.

Legend

• Orange round nodes are files
• white folders are collapsed directories
• blue nodes are external dependencies
• red edges are invalid (by dependency-cruiser validation rules)
• orange edges are circular dependencies
• an edge always points from the source (import) to the target (export)