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 the package.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!