Document and preview ReactJS components with JSDoc - Wojciech Krysiak

September 04, 2019 0 Comments

Document and preview ReactJS components with JSDoc - Wojciech Krysiak

 

 

Wojciech Krysiak

It has been a very busy week at SoftwareBrothers (again) - we released another version (1.2) of better-docs — theme for JSDoc with a brand new “@component” plugin.

Long story short, it builds documentation (with a live preview) from your React components. To see how it works check out the example documentation: https://softwarebrothers.github.io/admin-bro-dev/ValueBlock.html and scroll down to the editor where you can modify the component code.

In this brief article, I will show you how you can add this to your React project. Interested? Let’s start!

I assumed that you know what JSDoc is — if you don’t, check out the project page.

Setting up React project

Let’s start with a simple react project created with create react app.

npx create-react-app my-documented-app
cd my-documented-app

Setting up JSDoc with better-docs

Next, we have to install 2 dev dependencies:

yarn add --dev jsdoc better-docs

and we also have to install parcel-bundler globally — it is used to bundle the files so that we can see live examples of our documented components:

yarn global add parcel-bundler

Now, let’s define a JSDoc configuration file: jsdoc.json and put it in the root folder of your project:

It sets better-docs as a template, adds “@component” plugin and defines that all the docs will be put to ./docs folder.

You can read more about jsdoc.json files here.

The last thing would be to create a docs command that will generate the documentation.

In thepackage.json file add the following script (below eject ):

"docs": "jsdoc -c ./jsdoc.json"

now you can test it by running:

yarn docs in your terminal. It should generate blank documentation in ./docs folder, where you will find index.html . You can open it in your browser and see how it looks.

Add a component with JSDoc documentation

Now the fun part. Let’s add a new component with JSDoc tags. Name it Documented.js and put in ./src directory.

The component renders a paragraph with some styles. In JSDoc comments, it has a description and we mark it as Component by adding “@component” tag.

And we also have a “@example” tag where we show how the component can be used.

Below there are propTypes with the definitions of our component’s inputs with default values (defaultProps).

Having all of that we can rerun the docs command:

yarn docs

If everything went fine you should be able to visit the index.html and navigate to the new “documented” component which looks like this:

Props were taken from the code automatically and you can edit the code live.

Summary

This is it. I’ve showed you how you can use “@component” plugin. Of course, there are more advanced topics like:

  • how can I set up a CSS framework like Bulma or bootstrap?
  • how can I set up a redux store?
  • how can I use styled-components or CSS modules?

Answers to all of those questions can be found on the better-docs GitHub page so see you there!

One last word…

If you like better-docs - star the repo on GitHub so more people will see how cool that is!


Tag cloud