doc-prop-types

Generate prop documentation at runtime in tandem with prop-types.

This library is for users building development environments, styleguides, storybooks, or anything where you'd like to know about a React component's props at runtime. Because the same API sets the PropTypes as well as the documentation, there can never be a divergence between the two!

Unlike react-docgen, which parses source files of React components and uses that to output JSON that describes that component's props, doc-prop-types is used at runtime, which means that it can do two things that react-docgen has some difficulty with:

• Use prop-types from imported components (e.g. ImageButton.PropTypes = { ...Button.propTypes })
• Allow you to write and structure your components any way you like (multiple components per file, unusual component declarations)

The only price of this is that this is nearly a drop-in replacement for React's own prop-types package: props are assigned using a assignPropTypes function instead of by assigning to the propTypes property.

Installation

yarn add doc-prop-types

Usage example

Before

import PropTypes from "prop-types";

PetOwnerInfo.propTypes = {
  name: PropTypes.string.isRequired,
  age: PropTypes.number,
  pet: PropTypes.shape({
    name: PropTypes.string.isRequired,
    species: PropTypes.oneOf("Dog", "Cat")
  })
};

After

import DocPropTypes, { assignPropTypes } from "doc-prop-types";
// Or with ES5 and `require`:
// var DocPropTypes = require('doc-prop-types').default ;
// var assignPropTypes = require('doc-prop-types').assignPropTypes;

assignPropTypes(PetOwnerInfo, {
  name: DocPropTypes.string.isRequired,
  age: DocPropTypes.number,
  pet: DocPropTypes.shape({
    name: DocPropTypes.string.isRequired,
    species: DocPropTypes.oneOf("Dog", "Cat")
  })
});

The API of DocPropTypes is identical to that of PropTypes, with an exception for custom prop types (see below).

assignPropTypes will mutate and return the component given as the first argument, with the following new properties added to it:

• Component.propTypes will have vanilla proptypes so that React can do its type-checking.
• Component.docPropTypes will have DocPropTypes so that you can import them into other components.
• Component.propInfo will have a description of the props assigned to the component (the good bit).

The description on propInfo will look something like this (in the case of the above example):

{
    name: {
      type: 'string',
      isRequired: true
    },
    age: {
      type: 'number',
      isRequired: false
    },
    pet: {
      type: 'shape',
      isRequired: false,
      shape: {
        name: {
          type: 'string',
          isRequired: true
        },
        species: {
          type: 'oneOf',
          isRequired: false,
          enums: [
            'Dog',
            'Cat'
          ]
        }
      }
    }
}

Importing PropTypes from other files

Imported propTypes must also be DocPropTypes:

import Button from "./Button";

const ImagePropTypes = {
  src: DocPropTypes.string.isRequired
};

assignPropTypes(ImageButton, {
  ...ImagePropTypes,
  ...Button.docPropTypes
});

If it's valid JavaScript, you can structure and combine your DocPropTypes in whatever way you wish.

Custom prop types

DocPropTypes has one API difference with prop-types, and that's with how you specify custom proptypes:

// In component proptype definition
{
  customProp: myCustomPropType;
}

// With DocPropTypes
{
  customProp: DocPropTypes.custom(myCustomPropType);
}

Things this package doesn't do (yet)

The items listed below haven't been excluded for any philosophical reason. We either just haven't gotten around to it or don't know how to make a nice API for it!

• Doesn't document descriptions/comments to props

Contributing

Pull requests are more than welcome. Please make sure that tests pass (with yarn test), that linting passes (with yarn lint), and that any new functionality also includes tests. Thanks!