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
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
You can read more about
jsdoc.json files here.
The last thing would be to create a
docs command that will generate the documentation.
package.json file add the following script (below
"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
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 (
Having all of that we can rerun the
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.
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!