What good are components if nobody can understand how to find and use them?
React encourages you to build modular applications with components. Modularity brings all sorts of advantages, including improved reusability. But, when you aim to share and reuse a component, you better make sure it is easy to discover, understand and put to use. You need to document components.
Today, modern tools can help automate some of the documentation workflows and to turn the consumption of component documentation into a rich, visual and even interactive experience. Some tools even combine such docs as an integral part of the very workflow of sharing components.
To achieve beautiful component documentation without working too hard, I’ve gathered some of the best and most popular tools for documenting React components. Feel free to comment and add your own ideas and tools.
1. Bit
The platform for shared components.
bit.dev — Search and choose components by bundle-size, dependencies, labels and snapshot previews
Bit more than just a documentation tool for components. It’s an open-source tool that lets you encapsulate components with all their files and dependencies, and run them across different applications out-of-the-box.
The bit.dev platform lets you share and collaborate on components across your applications. All your shared components are made discoverable for your team to find and use in their projects and easily share their own components.
The components you share to bit.dev become discoverable in your team’s a shared component hub. You can search for components by context, bundle-size or even dependencies. You can quickly browse results based on visual snapshots of the actually-rendered components, and choose with your eyes.
→ Explore components on bit.dev
When you go into one of your component’s web-page, you will discover that Bit presents the component in a live playground so that you can play with it before choosing to consume it in your application. If you have JSDocs or an .md file as part of the code, Bit will parse and present these docs as well. If the components include unit-test files, Bit will run them in isolation and present the results as part of the documentation for every component.
When found a component you like to use, just use NPM or Yarn to install it. You can even use Bit to develop and update the components directly from any consuming application, so your team can collaborate and build together.
When sharing components through Bit you don’t have to set up any more repositories or tools, no need to refactor or change your code, and the same hub where you share components are where they become documented and discoverable, pretty much out of the box.
2. StoryBook & Styleguidist
StoryBook and StyleGuidist are too wonderful projects that help develop components in isolation while visually rendering and documenting them.
StoryBook
StoryBook* *is a development environment for UI components. It allows you to browse a component library, view the different states of each component, and interactively develop and test components. When building a library, StoryBook is a neat way to visualize and document components and different AddOns make it easier to integrate into your different tools and workflows. You can even reuse stories in unit-tests to confirm nuanced functionality.
StyleGuidist
StyleGuidist is an Isolated React component development environment with a living style guide. It provides a hot reloaded dev server and a living style guide that lists component propTypes and shows editable usage examples based on .md files. It supports ES6, Flow and TypeScript and works with Create React App out of the box. The auto-generated usage docs can help Styleguidist function as a documentation portal for your team’s different components.
- Also check out UI Zoo by Noam Elboim.
3. Codesandbox, Stackblitz & friends
Component playgrounds are a neat way to play with components and learn how they work. When you can combine them as part of your documentation (or as part of your shared-components workflow), playgrounds help you quickly learn how code works and decide if you want to use the component.
Codesandbox
Codesandbox is an online editor for quickly creating and playing-with small projects like components. After creating something interesting you can show it to others by just sharing the url. CodeSandbox features a live preview to show the result of the code while you’re typing and has extensions built to integrate into your different tools and your development workflow.
Stackblitz is an “online IDE for web applications” powered by Visual Studio Code. Much like Codesnadbox, StackBlitz is an online IDE where you can create Angular & React projects that are made shareable via a URL link. Like Codesandbox, it automatically takes care of installing dependencies, compiling, bundling, and hot reloading as you type. Take a look.
→ Find more component playgrounds for React:
11 React UI Component Playgrounds for 2019
*Useful online playgrounds and editors for your UI components*blog.bitsrc.io
- Also see: react-cosmos | react-live
4. Docz
Docz
Docz makes it easier to build Gtabsy-powered documentation websites for your code. It’s based on MDX (*Markdown + JSX) *to leverage markdown for component documentation. Basically, you can write an .mdx file anywhere in your project and Docz will streamline the process of turning it into a documentation portal of your own design deployed to Netlify. Useful right?
pedronauck/docz
*✍🏻It has never been so easy to document your things! - pedronauck/docz*github.com
5. MDX-docs
MDX-docs
MDX-docs lets you document and develop React components with MDX and Next.js. You can mix markdown with inline JSX to render React components. Write markdown as you normally would and use ES import syntax to use custom components in your document. Built-in components render JSX fenced code blocks as live previews with editable code, powered by react-live.
Take a look.
jxnblk/mdx-docs
*memo: Document and develop React components with MDX and Next.js - jxnblk/mdx-docs*github.com
6. React Docgen
React DocGen is a CLI and toolbox to extract information from React component files for documentation generation purposes. It uses ast-types and @babel/parser to parse the source into an AST and provides methods to process this AST to extract the desired information. The output / return value is a JSON blob / JavaScript object. It provides a default implementation for React components defined via React.createClass, ES2015 class definitions or functions (stateless components). Functional and powerful.
reactjs/react-docgen
*A CLI and toolbox to extract information from React component files for documentation generation purposes. …*github.com
Top comments (5)
I hadn't seen bit.dev before... interesting. How does it compare to say, sharing a storybook or docz for team collaboration? It appears fairly similar; but contributors can publish one component at a time?
Bit’s main mission is to maximize code reuse and to allow for a more fine-grained collaboration.
To that end, they have had to tackle two main obstacles on the way:
Sharing and collaborating on individual code components/ modules requires cumbersome solutions like monorepos - you can read more about it here: monorepos- please don't
More often than not, modules/components are simply not adopted by the team/organization (and are repeatedly re-written by the team members) because of either poor discoverability or simply because the components may require modifications to be used on their host projects and no tools are available to pull-request changes for a specific component or to push and share the modified component as a new component.
Bit solves these problems by tracking your component’s (with all their dependencies, specs, etc.) - all you have to do is configure your components’ folder (or manually choose individual files/folders) - then you can export (all of) them to Bit’s cloud (with a single command) where others can discover them, install them like packages (using NPM or Yarn) or import them to their projects (using Bit), and collaborate on them on their local projects).
There’s no need for long and tiresome configuration - you simply “tell” Bit where the components are and it does the rest by itself - it even builds and tests each component in isolation before exporting it to Bit’s cloud.
Whenever a new version of a component (that is installed on your project) is available, Bit notifies you so you may choose to update you local component.
After sharing components, they can easily be found on Bit’s cloud with a great UI and search engine.
When you find your component, you can tweak it and see it render on Bit’s live playground (before installing it)
Ah, that's neat - I'll have to try it out. I like the idea of no tiresome configuration :)
Thanks for the explanation!
Nice post. Thanks!
Can we add additional fields along with the Properties? "Name,Type,Default,Description" Along with that if we want to add additional properties, is that possible