In this tutorial, you will learn about React Styleguidist. React Styleguidist is a useful tool that you can use with your React.js application in order to auto-generate documentation. Manually writing documentation has several downsides, first, it's boring and second, it's very time consuming trying to keep it up-to-date. Every time someone updates the code you have to hope that they also update the documentation.
Setting up React Styleguidist
First, you will need to use web-pack if you want to use React Styleguidist. Installing and configuring web-pack is outside the scope of this project, however, if you want to learn more go here. To install React-Styleguidist run this command within your project:
Next, create a Styleguide.config.js in the root folder of the project to configure it as you need to. The purpose of this file is to export an object containing all of the information needed to configure React Styleguidist back to web-pack.
Let's say all your React components are stored within a folder called 'components', you could use a config similar to this one:
In the module exports, notice how we're also adding the web-pack config option. Use this option to tell the plug-in where to find your web-pack file.
How To Generate Documentation
Styleguidist provides two ways to view the documentation. You can either generate a static website so you can check your style-guide within source control. The other option is to dynamically server the pages from its own node server. I typically tend to use the static HTML version, however, the self-hosted server can be useful when you're writing code. If the server is up and running you can check that the documentation is updating as you write new code. To get going with a self-hosted server, run this command:
If everything runs correctly, you should be able to view the guide on port 6060, like so:
If you want to create your documentation as static HTML files so you can ship it with your code within source control, you can use this command:
After successfully running, documentation should get generated within a folder called 'style-guide'. Open the index.html and you should be presented with something similar to this:
As you can see above, in the left-hand panel, you will see a list of all the components. After you click on a component, you will be able to see its associated documentation within the main panel.
You can make the documentation within your Style-guide a lot more useful if you also use React PropTypes. Prop-types are really handy and I suggest you take some time learning about them. In a really large project that might contain hundreds of components, to know exactly what props each component takes and if they are required or not becomes challenging. Prop-types offers a way to describe properties from within each component.
Developers who are new to your codebase can have an easy way to look at a component and get a basic understanding of how they can get it working. Another benefit with prop-types is that if you start using them, React Styleguidist will also automatically add their descriptions into the style-guide.