Component Documentation & Development Environments: dumi vs Gatsby vs react-styleguidist vs Storybook vs VitePress

When building UI libraries or design systems, you need more than just code — you need a way to document components, show live examples, and let developers interact with them. The tools in this comparison (dumi, gatsby, react-styleguidist, storybook, and vitepress) all aim to solve this problem, but they do it in very different ways. Let’s break down how each works, what it’s best for, and how they differ under the hood.

📚 Core Purpose: What Problem Are We Solving?

All five tools help you create living documentation for React components, but their scope and architecture vary significantly:

• dumi and vitepress are documentation-first static site generators that support live component demos.
• gatsby is a full-featured static site generator that can be extended to document components.
• react-styleguidist and storybook are component development environments focused on isolated component testing and documentation.

This fundamental difference shapes everything from configuration to developer experience.

⚙️ Configuration & Setup: Zero-Config vs Plugin Architecture

dumi: Convention Over Configuration

dumi assumes you’re building a React component library and auto-discovers components based on file structure. No config needed for basic usage.

// .umirc.ts (optional)
export default {
  // Usually empty for simple docs
};

Place your component in src/ and write Markdown in docs/ — it just works.

vitepress: Minimal Config, Vite-Powered

vitepress is built on Vite and requires almost no setup. You write .md files and embed components directly.

// docs/.vitepress/config.js
export default {
  title: 'My Library',
  themeConfig: {
    nav: [{ text: 'Guide', link: '/guide' }]
  }
}

Components used in Markdown must be globally registered or imported via frontmatter.

gatsby: Plugin-Driven Architecture

Gatsby needs explicit plugins to handle React components in Markdown.

// gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-react-helmet`,
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        gatsbyRemarkPlugins: [
          {
            resolve: `gatsby-remark-component-demo`,
          }
        ]
      }
    }
  ]
}

You’ll need additional plugins like gatsby-remark-component-demo or custom MDX components to render live examples.

react-styleguidist: Focused on Props & Examples

Styleguidist scans your source code for components and JSDoc comments to auto-generate prop tables.

// styleguide.config.js
module.exports = {
  components: 'src/components/**/[A-Z]*.js',
  propsParser: require('react-docgen-typescript').withCustomConfig('./tsconfig.json').parse
}

It expects specific comment formats and folder structures.

storybook: Addon Ecosystem

Storybook uses a story-based approach where each component has explicit “stories” defining its states.

// Button.stories.js
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button
};

export const Primary = () => <Button variant="primary">Click me</Button>;

Configuration lives in .storybook/main.js and focuses on addons and webpack customization.

🧪 Live Editing: How Components Are Demonstrated

dumi: Markdown with JSX

Write JSX directly in Markdown files. The component is live-editable by default.

<!-- docs/button.md -->
# Button

```jsx
import { Button } from '../src';

<Button type="primary">Hello</Button>

### `vitepress`: Vue-like SFC in Markdown

Use a special `<script setup>` block or global components to embed React components.

```md
<!-- docs/guide.md -->
# Guide

<script setup>
import { Button } from '../src/Button'
</script>

<Button>Click me</Button>

Note: React support in VitePress requires additional setup since it’s Vue-native.

gatsby: MDX Required

You need MDX to mix JSX and Markdown.

<!-- src/pages/button.mdx -->
import { Button } from '../src/components';

# Button

<Button variant="secondary">Live demo</Button>

Without MDX, you can’t embed live components in regular Markdown.

react-styleguidist: Code Blocks in Markdown

Examples are written in fenced code blocks within Markdown files next to components.

// src/components/Button/Readme.md
```js
<Button primary>Push Me</Button>

The component is automatically available in the scope.

### `storybook`: Explicit Stories

Every demo must be explicitly defined as a story function.

```js
// stories/Button.stories.js
import React from 'react';
import { Button } from '../src';

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = { children: 'Primary', variant: 'primary' };

No implicit rendering — everything is opt-in.

🎨 Theming & Customization

dumi: Ant Design-Inspired

Uses Ant Design components internally, so theming follows AntD patterns. Custom themes require overriding CSS variables or using AntD’s theme system.

vitepress: Vue-Based Theme System

Theming is done through Vue single-file components. To customize the React component display area, you’d need to override VitePress theme components.

gatsby: Full Control

Since Gatsby renders everything through React, you have complete control over layout and styling. But you build everything yourself.

react-styleguidist: Limited Theming

Provides basic theme customization through config, but deep UI changes require ejecting or heavy CSS overrides.

// styleguide.config.js
module.exports = {
  theme: {
    color: {
      base: '#333'
    }
  }
}

storybook: Rich Addon Ecosystem

Offers extensive theming via addons like @storybook/addon-essentials and @storybook/theming. You can fully customize the UI shell.

// .storybook/preview.js
import { themes } from '@storybook/theming';

export const parameters = {
  docs: {
    theme: themes.dark
  }
};

📦 Build Output & Deployment

All tools generate static sites, but their output structure and performance characteristics differ:

• dumi and vitepress produce highly optimized static sites with minimal JavaScript.
• gatsby generates static HTML with optional hydration, but bundle size can grow with plugins.
• react-styleguidist outputs a single-page app with all components loaded upfront.
• storybook creates a SPA where stories are lazy-loaded, but the manager UI adds overhead.

For pure documentation sites with light interactivity, dumi or vitepress win on performance. For complex component exploration, Storybook’s runtime is justified.

🔄 Hot Reloading & DX

• dumi: Fast HMR powered by Umi (Webpack 5).
• vitepress: Instant HMR via Vite’s native ES modules.
• gatsby: Slower rebuilds due to full GraphQL layer.
• react-styleguidist: Decent HMR but can be slow with large libraries.
• storybook: Excellent HMR with addon support for controls, actions, and accessibility testing.

🧩 Real-World Scenarios

Scenario 1: Open Source React Component Library

You’re publishing a UI kit on npm and need clean docs with live examples.

• ✅ Best choice: dumi
• Why? Built specifically for this use case, zero-config, and integrates with npm publishing workflows.

Scenario 2: Internal Design System with Complex Components

Your team builds advanced components (data grids, charts) that need detailed interaction testing.

• ✅ Best choice: storybook
• Why? Addons for knobs, accessibility, and testing provide deep inspection capabilities.

Scenario 3: Simple Documentation Site with Some Demos

You have a small utility library and want a fast, lightweight docs site.

• ✅ Best choice: vitepress
• Why? Blazing fast, minimal setup, and perfect for content-heavy docs with occasional demos.

Scenario 4: Legacy Project with Existing Gatsby Site

You already use Gatsby for your main site and want to add component docs.

• ✅ Best choice: Extend Gatsby with MDX
• Why? Avoids maintaining a separate docs infrastructure.

Scenario 5: Small Team with TypeScript Components

You want auto-generated prop tables from TypeScript interfaces.

• ✅ Best choice: react-styleguidist (with react-docgen-typescript)
• Why? Excellent TypeScript integration out of the box.

⚠️ Important Notes on Maintenance

As of 2024:

• react-styleguidist is in maintenance mode. The official README states: "Styleguidist is in maintenance mode. We recommend using Storybook for new projects."
• gatsby, storybook, dumi, and vitepress are actively maintained with regular releases.

If starting a new project, avoid react-styleguidist unless you have specific legacy requirements.

📊 Summary Table

💡 Final Recommendation

• Choose dumi if you’re building a React component library and want documentation that ships with your package.
• Choose storybook if you need a full component development environment with testing, accessibility, and interaction controls.
• Choose vitepress if your priority is speed and simplicity for content-heavy documentation with occasional demos.
• Choose gatsby only if you’re already invested in the Gatsby ecosystem or need its data layer for documentation.
• Avoid react-styleguidist for new projects — use Storybook instead.

The right tool depends on whether you’re optimizing for documentation delivery (dumi, vitepress) or component development workflow (storybook). Don’t over-engineer — pick the simplest tool that solves your actual problem.