Recently I thought to myself: fairly frequently I dive into a big JS codebase and need to poke around for a while to get acquainted with the project structure, wouldn’t it be nice if I could have a more visual way of seeing the whole thing to make sense of it all?

It was this need I was trying to fill when I embarked on my open dev project last Friday. In this post I’ll try to walk through the steps I took so you can replicate them. If you want to just to play with the final project, it’s available as an npm module named jsviz (npm: jsviz, GitHub: jeffcarp/jsviz).

Representing the structure

Due to the way CommonJS works, circular dependencies are impossible. That means that if we map all the require calls in a JS project, the resulting structure is a directed acyclic graph.

The way I chose to represent this in JavaScript was an Object of Arrays. Each key on the Object was a file or a module (the vertices), which contained an Array of the files or modules it required (the edges). Here’s what I had in mind:

taco.js:

var fs = require('fs');
var salsa = require('./salsa.js');

salsa.js:

var fs = require('fs');

Resulting graph:

var graph = {
  "/taco.js": ["fs", "/salsa.js"]
  "/salsa.js": ["fs"]
};

Walking the syntax tree

So to begin, I read in all the JS files from a directory using the glob package.

var graph = {};
var targetDir = './path/to/project';

glob(targetDir+'/**/*.js', {}, function (err, files) {
  // ...
});

Then I had to parse out all the require calls from each file. I wanted to do this the “right way” (e.g. not using regular expressions). Fortunately there are tools out there that make parsing and iterating through a JavaScript syntax tree super easy - like esprima and estraverse, respectively.

To generate a syntax tree using esprima, it’s as simple as passing in a string to esprima.parse:

files.forEach(function (fileName) {
  var contents = fs.readFileSync(fileName, 'utf8');
  var ast = esprima.parse(contents);
  graph[fileName] = graph[fileName] || [];
  // ...
});

Next, in order to pick out all the require calls, we need to visit every node in the syntax tree and see if it’s a require call. This can be done super easy with estraverse. If it is requireing something, we can add its target to the graph.

estraverse.traverse(ast, {
  enter: function (node, parent) {
    if (nodeIsRequireCall(node)) {
      var requireTarget = node.arguments[0].value;

      if (graph[fileName].indexOf(requireTarget) === -1) {
        graph[requireTarget] = graph[requireTarget] || [];
        graph[fileName].push(requireTarget);
      }
    }
  }
});

function nodeIsRequireCall(node) {
  return (
    node &&
    node.type === 'CallExpression' &&
    node.callee &&
    node.callee.name === 'require'
  );
}

Note: the actual code has a couple of filtering lines I left out of these snippets for the sake of readability. See the final source here.

Visualizing the graph

Now we have a reasonably accurate dependency graph. I searched Google for d3 directed acyclic graph and found this example. I implemented it, tweaked it a little, and got something that didn’t look half bad. Here’s jsviz visualizing jsviz:

Visualization of jsviz project with jsviz

The arrows point to what a file is requireing. So in the example above, /cli.js requires /viz.js.

Here’s one of jsdom. Looks like the layout needs some tweaking to be more readable.

Visualization of jsdom project with jsviz

You can play with these on the gh-pages branch of jsviz: