David Boyne

Technical Lead @Comparethemarket. Organiser of Agile-Peterborough. Speaker & evangelist of JavaScript, Agile Principles and helping others.

Automating documentation for your React components

Building and sharing components is one of the most powerful features of React, but what good are our components without any documentation?

I have recently been involved in a project creating components that will be adopted by a wide range of developers and have learnt a way to easily automate component documentation.

In this post we will cover why you might need to document your components and how you can easily achieve this with React.

Why document components?

So firstly you might be thinking why do we need to document our components?

To be honest it really depends on what you are building and who will be consuming your components.

When building web applications in React our tests could be enough documentation for our components.

But if your writing a large scale application or large number of components that are used throughout your business or for a online community then documentation is key.

If we look at some examples like React Bootstrap or Material UI their documentation really helps developers get setup and utilising their components within minutes.

Taking inspiration from these projects, I wanted to do something similar for my project and managed to do it with some awesome tools I found along the way.

So lets take a look at them.

react-docgen

react-docgen is a CLI and toolbox to help extract information from React components, and generate documentation from it.

The idea is simple. We pass our component into react-docgen and it will return an object.

Lets take a look at the example on the react-docgen GitHub page.

Component Example
var React = require('react');

/**
 * General component description.
 */
var Component = React.createClass({
  propTypes: {
    /**
     * Description of prop "foo".
     */
    foo: React.PropTypes.number,
    /**
     * Description of prop "bar" (a custom validation function).
     */
    bar: function(props, propName, componentName) {
      // ...
    },
    baz: React.PropTypes.oneOfType([
      React.PropTypes.number,
      React.PropTypes.string
    ]),
  },

  getDefaultProps: function() {
    return {
      foo: 42,
      bar: 21
    };
  },

  render: function() {
    // ...
  }
});

module.exports = Component;
JSON output
{
  "props": {
    "foo": {
      "type": {
        "name": "number"
      },
      "required": false,
      "description": "Description of prop \"foo\".",
      "defaultValue": {
        "value": "42",
        "computed": false
      }
    },
    "bar": {
      "type": {
        "name": "custom"
      },
      "required": false,
      "description": "Description of prop \"bar\" (a custom validation function).",
      "defaultValue": {
        "value": "21",
        "computed": false
      }
    },
    "baz": {
      "type": {
        "name": "union",
        "value": [
          {
            "name": "number"
          },
          {
            "name": "string"
          }
        ]
      },
      "required": false,
      "description": ""
    }
  },
  "description": "General component description."
}

The JSON object we get back has extracted documentation from our component.

The Object holds all the props we defined in the component.

For each prop it returns the type, if it is required, the description and any default values.

So using the CLI is great, but how do we use this in a React application and automate the process? Its actually pretty straight forward so lets have a look.

Using react-docgen inside our React application

First thing we should do is install react-docgen

npm install --save react-docgen

Next lets import it into our React application

import {parse} from 'react-docgen';

Now we have the ability to parse any component and get its documentation back. But to use the parse function we need to import our components as strings.

So lets import a component as a string using the raw-loader.

Using raw-loader

First we need to install raw-loader.

Installing raw-loader
npm install raw-loader

After setting up raw-loader with webpack we can import any file in its raw format.

Import file in its raw format
import Component from '!raw!./Component';

Note: Component will come back to us as a string and not a React component.

With the component as a string we can pass it into our parse function from react-docgen to get some documentation back.

import {parse} from 'react-docgen';
import Component from '!raw!./Component';

const componentDocs = parse(Component);

In this example componentDocs will hold the components documentation as a JSON object.

What does this mean?

For large scale React applications being able to get documentation from our components might be a great idea.

Using react-docgen and raw-loader we could easily create a simple user interface to represent our library of components and their documentation for other developers to consume.

Using the information we could visually show our components in use, our component props details and our components description.

Here is an example of what I’ve been working on and what you can achieve with react-docgen.

Basic React application that renders component documentation

The Button’s description and props are automatically generated anytime the component changes making sure the documentation is always kept up to date for other developers.

This post was inspired by reading material-ui project on GitHub.

Checkout the material-ui project on GitHub for some awesome examples on how they are using this technology to help drive their component documentation.

If you have any questions just tweet me, or leave a comment.

SHARE