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 ESDOC manual, 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 standard plugin code 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 this post 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
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:
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.