Bundling ESDOC plugins together

David Barral
Apr 22 · 3 min read
Photo by on

For the past two years we’ve been using to document our JavaScript projects. It’s a nice tool but has several shortcomings. In a I’ve explained how to overcome those shortcomings by getting advantage of ESDOC plugins. In most of our projects we end using the same plugins all the time and our esdoc.config.js files end having a lot of repetitive boilerplate.

Take the following config as an example. You can see that most of the code just states that we want to use some standard or custom plugins with no additional config or with some defaults. We use the same plugins on each and every project. Not so DRY.

Don’t worry. It’s possible to get rid of all the boilerplate using the ESDOC plugin system.

It’s already solved

If you take a look at the , you’ll notice that only one plugin is needed to generate your docs, the esdoc-standard-plugin. This plugin adds support to customize the output, add a tutorial, integrate the coverage reports, lint the code, etc. So much functionality bundled in just one plugin. Oh, wait! That’s exactly what we wish to do with our default set of plugins.

Learning from the code

ESDOC is not the best documented tool out there, but much can be learned just by reading the source code. Digging into the we found our answer. This plugin uses the onHandlePlugins lifecycle method to push additional plugins and their default options into the ESDOC config (you can take a look at to understand how ESDOC plugins work and how it’s possible to modify from a plugin the whole ESDOC config).

So, taking the cue from the standard-plugin we can build our plugin bundle.

  • It will be distributed as an npm package to be easily shared.
  • It will depend on both standard plugins and our own custom plugins. Custom plugins will also be distributed as npm packages.
  • It will define a set of sane default options for each plugin. The user could override these options in the ESDOC config file. Config options will be scoped by unique keys, one for each plugin.

The plugin code could be as follows:

And this could be the package.json:

Notice that it’s also possible to bundle plugins and distribute them in this package (just push the plugin file path instead of a module name), however, distributing each plugin on its own npm package gives bigger flexibility.

With this setup in place, our new esdoc.config.js could be much simpler and DRY:

Summing up

This is just another trick you can pull off using the ESDOC plugin system. Once you have defined a set of plugins to tune your docs, the next logical step is to bundle them to reduce boilerplate, share some sane defaults and thus, simplify your ESDOC config file. By using a package with overridable defaults it’s easy to share improvements between many projects with little or no effort at all.

Trabe

We are a development studio. We use Java, Rails, and JavaScript. This is where we write about the technologies we use at Trabe.

Thanks to Asís García and Iván Lomba.

David Barral

Written by

Co-founder @Trabe. Developer drowning in a sea of pointless code.

Trabe

Trabe

We are a development studio. We use Java, Rails, and JavaScript. This is where we write about the technologies we use at Trabe.