Documenting React Components with docz

Pic Credits: docz website

Well when you are working on large scale projects and you are building reusable components from scratch and the number of components becoming more over time and new developers are coming in to the project, there is a need to document the components because you might get questions like “I want to build a new component for my new feature.. Is it already there? What it does? Does it work the same I want it to be?..

These questions are quite valid and going through the entire components to find out where it is and how it works is time consuming and it not a good practice. Documentation and putting it live on a web server solves this problem. Today we are going to see how we can create documentation of React Components and use them in your projects so that we can save time working on our feature. We can scale these components based on our need instead of creating another one from scratch.

To build documentation of React Components we will use docz

What is Docz?

Documenting code is one of the most important and time-heavy processes when developing software.

A lot of time is spent on building and maintaining custom documentation sites.

Docz was created to solve this problem.

Docz enables you to quickly create live-reloading, seo-friendly, production-ready documentation sites with MDX and customize the look, feel and behavior when required by leveraging GatsbyJS and Gatsby theme shadowing.

Principles:

We started by looking over the options available when you want to create your design system or document your project. We borrowed the best ideas from each and came up with the following guiding principles :

  • Zero config and easy to learn. Avoid unnecessary build steps with confusing setups.
  • Blazing fast. Built with performance in mind from the start.
  • Easy to customize. Create something that will be easy to use and customize.
  • MDX based. Use the best standard for writing documentation.

In this tutorial we will not go through docz but we will only see how can we incorporate docz in our existing React application and create documentation for our already present React Components.

Before moving to this tutorial I would suggest you to go through the docz website

Let’s dive in…..

Let’s suppose we have below React Application and we would like to generate documentation for our components.

docz components

We are trying to build the documentation of our AlertComponent with docz.

docz runs on gatsby on the wrapper. so when we need to run a documentation site inside our app we are spinning up a Gatsby server which is a wrapper on React. To learn more on Gatsby follow this link:

Step 1:

Add a .mdx file inside your component folder. For e.g(AlertComponent.mdx)

AlertComponent.mdx

If you are using pre-processing styles like SCSS or LESS in your components, then you should have some extra config to let know Gatsby that you need to compile the pre-processors like this.

For SCSS:

  1. Install node-sass and gatsby-plugin-sass
# npm
npm install --save node-sass gatsby-plugin-sass

# yarn
yarn add node-sass gatsby-plugin-sass

2. Add the plugin to your gatsby-config.js

//gatsby-config.js
module.exports = {
plugins: ['gatsby-plugin-sass']
}

You should now be able to use sass in your components!

For LESS:

  1. Install gatsby-plugin-less
# npm
npm install --save gatsby-plugin-less
# yarn
yarn add gatsby-plugin-less

2. Add the plugin to your gatsby-config.js

//gatsby-config.js
module.exports = {
plugins: ['gatsby-plugin-less']
}

You should now be able to use less in your components!

Step 2:

Add the below line in your “scripts” object in package.json to run a dev server for your documentation website of your React Components.

"docz-serve": "yarn docz serve"
package.json

Now if you run npm run docz-serve you will see something like this:

docz running locally

Once your development server is up you will see a .docz folder in your directory which is serving all your static docz files. You should put it in .gitignore

Thats it!!!

Thanks for reading! If you have any questions, feel free to reach out at rajrock38@gmail.com, connect with me on LinkedIn, or follow me on Medium and Twitter.

If you found this article helpful, it would mean a lot if you gave it some applause👏 and shared to help others find it! And feel free to leave a comment below.

--

--

--

Full Stack Developer • Interested in JavaScript.Everything() • Writes on programming • Simple rule:Code less code efficiently

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Functional programming in JavaScript using(map, filter and reduce)

Full Stack Boilerplate saves the day

Few More Random Topic related to js or not!

All About React Router

Phaser Manifest Loader

Taking a quick look at Testing 👀

Namespace in JavaScript

Create a mobile app with Vue3 + Quasar + Capacitor + Firebase — journal #1

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Rajdeep Chandra

Rajdeep Chandra

Full Stack Developer • Interested in JavaScript.Everything() • Writes on programming • Simple rule:Code less code efficiently

More from Medium

Server-side search in React-table

Implementing a scrollbar for React Flow

Build a full-stack framework on React

React Context API: Getting Started