real-world-samples.md

Real world projects. Dependency cruised.

Some popular projects on npm

Commander

tj/commander.js - For command line parsing - and cooking command line interfaces.

Chalk

chalk/chalk - For colouring strings in the terminal. A typical Sorhus style micro module that uses other micro modules to accomplish its goals.

Yarn 2 ('berry')

yarnpkg/berry - package manager.

When your app becomes big, dependency graphs on module level will become impractical. Dependency-cruiser can consolidate modules (+ their dependencies) and colour them. Consolidation works out of the box for many repositories, but can be configured to your own liking.

Here's the resulting get high level dependency graph for berry:

howto

To get the above graph we used berry-dependency-cruiser-config.js. To generate it yourself do this in the root of the berry repo:

• yarn (with yarn v2 :-))
• yarn add -D dependency-cruiser
• copy berry-dependency-cruiser-config.js to the root of the repo
• add this script to package.json (so don't use the globally installed depcruise or even the locally installed one - yarn's pnp resolution won't work otherwise:)

  "dc": "depcruise --version && depcruise --config berry-dependency-cruiser-config.js --output-type err packages",
  "depcruise:archi": "depcruise --config berry-dependency-cruiser-config.js --output-type archi packages | dot -T svg | tee berry-high-level-dependencies.svg | depcruise-wrap-stream-in-html > berry-high-level-dependencies.html",
  

• run yarn depcruise:archi

react

facebook/react - "a JavaScript library for building user interfaces".

Also high level:

howto

To get the above graph we used react-dependency-cruiser-config.js. To generate it yourself do this in the root of the react repo:

• prepare

git clone git@github.com:facebook/react.git
cd react
yarn
yarn add -D -W dependency-cruiser
rm -f react-dependency-cruiser-config.js
wget https://raw.githubusercontent.com/sverweij/dependency-cruiser/develop/doc/real-world-samples/react-dependency-cruiser-config.js

• Add these run-scripts to the package.json:

    "dc": "depcruise --version && depcruise --config react-dependency-cruiser-config.js -T err packages/*/{*.js,src}",
    "depcruise:archi": "depcruise --config react-dependency-cruiser-config.js -T archi packages/*/{*.js,src} | dot -T svg | tee react-high-level-dependencies.svg | depcruise-wrap-stream-in-html > react-high-level-dependencies.html
  

• yarn depcruise:archi

Safe-regex

substack/safe-regex - for sanity checking regular expressions against exponential time errors. For everyone who enables users to input regular expressions in.

Resolve

substack/node-resolve - resolves (node) module names to files on disk.

Yargs

yargs/yargs - Another library to parse command line options/ cook command line interfaces.

TypeScript

It is possible to use dependency-cruiser to infer dependencies of typescript projects.

We got the picture of tslint by running this in its source folder:

dependency-cruise -T dot -x node_modules -v -- src/index.ts  | dot -T png > tslint-without-node_modules.png

(Yep, that's all - no separate transpilation steps necessary ...)

tslint

palantir/tslint - linter for typescript.

The orange lines are warnings for circular dependencies, which occur around two of tslint's 'barrel' index.ts modules:

CoffeeScript

In the same vein dependency-cruiser directly supports CoffeeScript.

In the src folder of the CoffeeScript repo run this:

depcruise -x node_modules -T dot . | dot -T png > coffee-script-coffee-without-node_modules.png

CoffeeScript

jashkenas/coffeescript - the CoffeeScript transpiler:

(You see one module flagged as unresolvable - this is the parser code that the CoffeeScript build script generates jison into the folder with transpiled JavaScript.)

My own projects

dependency cruiser

Dependency cruiser used on itself, focusing on internal dependencies only, on three levels of abstraction - high level, folder and modules. A small custom theme in its configuration colours the various main parts (extract, validate, report) and the dependencies to them. Click for slightly more interactive versions.

high level overview ('archi')

folder level overview ('ddot')

detailed overview ('dot')

state machine cat

sverweij/state-machine-cat - an interpreter for writing nice state diagrams. Click for a slightly more interactive version. As you can see this graph does not group modules from same folders into clusters. Instead it uses only colors for 'grouping' and notes the folder name in the nodes. It's what the 'flat' graph reporter does for you. See the howto foldout below to see how to reproduce it.

(For this too: click for a slightly more interactive version)

howto

git clone git@github.com:sverweij/state-machine-cat.git
cd state-machine-cat
npm install
npx depcruise src bin/smcat --progress \
    --config config/dependency-cruiser-graph.js \
    --output-type flat \
  | dot -Tsvg \
  | tee docs/dependency-cruiser-graph-flat-dot.svg \
  | npx depcruise-wrap-stream-in-html \
  > docs/dependency-cruiser-graph-flat-dot.html

mscgen.js

mscgenjs/mscgenjs-core - an interpreter library for turning text (in MscGen or two other DSLs) into sequence charts. Click for a slightly more interactive version.