Documentation makes your reusable components comprehensible and discoverable. It is a crucial part of every component library.
In this article, we will be looking at five tools that make documenting React components, an easy task.
Bit is a tool that goes way beyond automating component documentation. It takes care of the entire process of building a shared component library.
- Bit lets you share individual components from any project. You don’t need to maintain an additional repo for your component library. Each component can be versioned independently and exported to a shared library on bit.dev, from any repo/project you choose.
- Bit builds and tests components in isolation to validate reusability. Components are built and tested in isolation before being shared, to make sure they’re truly reusable and bug-free.
- Bit auto-generates documentation. Every component shared on bit.dev is analyzed and its API reference is automatically extracted, parsed and presented right in the component page on bit.dev. Every component can be given examples that render in Bit’s playground.
- Bit takes care of organizing and segmenting your components. Bit makes sure components are easily found using its semantic search, automatically generated labels (‘button’, ‘react’) and smart filtering (Size, dependencies, etc.)
Here’s a short example, using a simple to-do app:
Let’s say I want to export my app’s components to a shared collection (library)
Initialize a workspace and log in:
$ cd basic-todo-app
$ bit init
$ bit login
Add (all) components:
$ bit add src/components/
Configure a React compiler (components are built independent of your project’s build configurations) :
$ bit import bit.envs/compilers/react --compiler
Tag and export to a shared collection (create your own collection in bit.dev):
$ bit tag --all 1.0.0
$ bit export username.collection
2. React Styleguidist
This tool is best suited for component-driven projects and updates the documentation in real-time while your components are being created and edited. It lists the prototypes and displays the document in an editable Markdown format, with support for ES6, Flow and TypeScript.
Usually, documentation tools display the current condition of a component at a given time. StyleGuidist can display multiple variations and states of a given component. It also allows you to reuse UI patterns, this helps in scaling the UI.
StyleGuidist will create centralized documentation for components that are reused across the application. This will be valued by the team, due to the ease of reference.
Create your project using the “Create React App” command. Then you can install the Styleguidist in your project folder.
After installation, you can run Styleguidist and start your localhost server:
To customize the style guide for your project, you can create a “styleguide.config.js”. This maintains your settings like default port number, components, section, and title.
As you create components, propTypes and code comments will be generated automatically.
Docz can be installed using yarn:
You can now create the
.mdx file within your application. These
.mdx files can be seen on localhost after running Docz with the following command:
You can create a static version of documents using the following command:
You can also add those two commands in the package.json like shown below:
You can have the
.mdx file in the component folder itself. This organizes the application in a more orderly manner.
You can create the MDX file with a Frontmatter of name, menu, routes, and imports. This file can be viewed in your dev server on the path mentioned in the route.
If you prefer a less stylish and low-level tool to document your components, react-docgen is a good tool and it’s CLI based.
It creates documents by extracting information from React components. It uses AST (Abstract Syntax Tree) types to represent the abstract structure using nodes. Babel parser is used to parse the source into the AST structure. The AST structure is processed to get the output in JSON blob.
You can install the react-docgen using yarn or npm as follows:
Once you install the react-docgen, executable is created to convert single, multiple or an input stream.
The CLI of the docgen can be used along with programmatic APIs. To create documents using CLI, we can run the below command with the options provided by the docgen.
React-docgen uses components exported by React.createclass. This behavior can be changed using the –resolver option.
APIs can be created to extract and customize component information.
Source code is analyzed in two parts:
- Finding the AST nodes defining components.
- Extracting the required information from these nodes.
Using parse we can customize the behavior as it accepts multiple arguments like source, resolver, handlers.
Docgen supports projects using Flow and Typescript. These projects have advanced type systems than projects using React.PropTypes. Though it can capture these types, currently it does not capture the type if they are imported or declared in different files.
For example, check the following code
It will give the following output:
This is a widely used open-source tool and it does not interfere with the project as it runs outside the main component. Storybook documents dependencies between isolated components. Furthermore, Storybook supports addons and has a customizable API. It works for React and React-Native, Vue and Angular.
You can set up Storybook using npx. Install the boilerplate files for Storybook inside the project folder with the following command:
Storybook automatically detects the “package.json” file in order to identify dependencies. If the detection fails, or to use it with HTML, use the following command:
Once the installation is complete, you can run Storybook using npm:
Run your application on localhost and the following output will be seen, if everything was installed and configured successfully:
Once you create the stories of components, for example — like Button, check out the Storybook for your component. Below is the example of “storiesOf” Button module.
There are many ways in which we can use Storybook to document our components:
Design Systems: The design system is created using components and is reused in different parts of the project. These systems are easily manageable and scalable in larger projects. Using Storybook, you can create the documents of these designs without much of an effort.
Component Library: Documentation of Component-based applications will be maintained separately for each component. Storybook maintains the component library in location and also tests each state of the components.
Visual Testing: We can integrate visual tests with the component library, using the add-ons provided by Storybook.
Team Sharing: Storybook can be deployed as a static site. The site will be independent of any projects. These sites can be shared with the team to obtain feedback regarding the current components. This increases collaboration between teams.
Modern tools have made documenting React components effortless. There are many options like Storybook, Styleguidist, and React-Docz that can be used to automate documents and display them on the localhost. React-docgen is a low-level tool to extract information.
Clear documentation improves collaboration within the team while helping new coders to learn about these components easily.