React Autodocs Utils

Tool to get React component metadata: PropTypes, descriptions, prop comments and alike.

Some of the features:

• supports javascript and typescript components,
• tries its best to extract data from composed components
• goes into node_modules and tries to parse components from there
• looks for readme.md files
• looks for component.driver.js files and parses them (useful to automate component testkit documentation)

Install

npm i react-autodocs-utils --save-dev

Usage

As node module

const gatherAll = require('react-autodocs-utils/src/gather-all');
const path = './path/to/react-component.js';

gatherAll(path).then(metadata => {
  // `metadata` is an object with component metadata, detailed below in this README
});

As CLI

$ node_modules/react-autodocs-utils/index.js path/to/react-components.js

component metadata is printed in stdout

Example

given component.js:

import React from 'react';
import {oneOf, node} from 'prop-types';

export class Component extends React.PureComponent {
  static propTypes = {
    thing: oneOf(['first', 'second']),

    /** i am description about `children` prop */
    children: node.isRequired
  }

  render() {
    return <div/>;
  }
}

await gatherAll('./component.js') will return the following JSON:

{
  "props": {
    "thing": {
      "type": {
        "name": "enum",
        "value": [
          {
            "value": "'first'",
            "computed": false
          },
          {
            "value": "'second'",
            "computed": false
          }
        ]
      },
      "required": false,
      "description": ""
    },
    "children": {
      "type": {
        "name": "node"
      },
      "required": true,
      "description": "i am description about `children` prop"
    }
  },
  "description": "",
  "displayName": "Component",
  "methods": [],
  "readme": "source of `./readme.md` if exists, otherwise empty string",
  "readmeAccessibility": "source of `./readme.accessibility.md` if exists, otherwise empty string",
  "readmeTestkit": "source of `./readme.testkit.md` if exists, otherwise empty string",

  // metadata of exported methods in *.driver.js, *.protractor.driver.js or *.pupeteer.driver.js
  "drivers": [
    {
      "file": "component.driver.js",
      "descriptor": [
        {
          "name": "click",
          "args": [],
          "type": "function"
        }
      ]
    },
    {
      "file": "component.pupeteer.driver.js",
      "descriptor": [
        {
          "name": "element",
          "args": [],
          "type": "function"
        }
      ]
    }
  ]
}

With this information it is easy to display documentation with regular React components.

It is used heavily in wix-storybook-utils. Live example available at wix-style-react storybook.

API

gatherAll(path, options)

const gatherAll = require('react-autodocs-utils/src/gather-all')

• path - string, path to a React component file which should be parsed
• options - object supporting the following setting flags to adjust the parser:
  • skipPropsWithoutDoc - boolean. Skips component props that have no JSDOC comment

Contribute

• git clone [email protected]:wix/react-autodocs-utils.git
• npm install
• npm test

Jest used to run tests.

• jest --watch