ReactJS Component Documentation

- Gaurav

The patrons recommend the use of presentation, dumb and stateless components. The number of such components which have nothing to do with the business logic or the state of the application can be overwhelmingly high. One often starts with a  basic flat folder structuring for the components and very soon finds himself revisiting the structuring in to make the code more organized and maintainable. So, this article is dedicated to the documentation and the maintainability of the components.



Prototypes are a great way to represent the properties that the component expects. If one names the prop-types just right and also ensure that the components are well broken down into reusable chunks of code then the prop-types are self-documenting. But, there are two possible problems with relying on prop-types for documentation:

  1. Considerably Large Projects
    For a fairly large project, it will be impossible for somebody to find a component even if it is named very well and has an intuitive set of properties with apt prop types.
  2. PropTypes are possibly dead
    Although, 6 months ago from when I was drafting this post, zpao commented here that the prop types are valuable and will not be replaced overnight. However, there hasn’t been a lot of development on prop-types. The world is supposedly moving onto a static type checker flow.

    Another trouble with using prop-types is that even third party document automation modules cannot leverage prop-types anymore. Quoting from the react’s website.

    In a future major release of React, the code that implements PropType validation functions will be stripped in production. Once this happens, any code that calls these functions manually (that isn’t stripped in production) will throw an error.

I think I have presented a good case for not trusting prop-types for documentation.


Third Party Documentation Automation

Yes, I can smell documentation modules in the air. There is a cool module called react-docgen which is a command line tool for generating a very good json meta information or documentation for your react components. The tool is even capable of using the comments you right on the top of the reactjs component class into the json data extracted from the code. I highly recommend his tool. I am sure that soon such tools will be leveraged to create automated documentations for react components.

Cherry on the cake

Yes. Just how cool will it be to have a customized documentations with the support of custom layouts. One could use these as component libraries which might look as awesome as this one. This will indeed make your components reusable in the true sense.