🤩 Compare three powerful component document display tools

background

Some time ago, the department has been engaged in various component libraries in full swing.

To do the component library, it is inevitable to do the display and description of the components, and some documentation tools are used.

We have also tried several different documentation tools in our project. I will share some experiences with you today, I hope it will be helpful to you.

text

At present, our component library uses a total of three document tools, namely:

1. Story Book
2. Docz
3. Dumi

Below I will compare these three tools with and give some conclusions based on actual usage.

1. Story Book

StoryBook provides a development environment for UI components.

It allows you to browse the component library, view the different status of each component, and interactively develop and test components. It currently supports front-end libraries and frameworks such as react , vue , and angular

Code example

// Button.stories.tsx
import React from 'react';
import { Story } from '@storybook/react';

// We create a “template” of how args map to rendering
const Template: Story<ButtonProps> = (args) => <Button {...args} />;

export const Primary = Template.bind({});

Primary.args = {
  primary: true,
  label: 'Primary',
};

Storybook provides interactive component writing, Template.bind({}) components through args exposes interactive properties through 0609296db23e47.

And the supported component library is rich, but in addition to providing examples, the writing of documents also needs to be compatible with interactive modes.

Rendering example

For example, our SSC-UI-Vue-Pro component library:

import STrackingHistory from './tracking-history.vue';
import './style/index.less';

export default {
  title: 'Design System/展示/TrackingHistory',
  component: STrackingHistory,
  parameters: {
    docs: {
      description: {
        component: '订单历史追踪，主要按时间和状态维度跟进',
      },
    },
    design: {
      type: 'figma',
      url:
        'https://www.figma.com/file/zi4Lcb2H2K5JikFKeEvPD7/WMS%E5%85%B8%E5%9E%8B%E6%A8%A1%E6%9D%BFV1.1?node-id=2974%3A595',
    },
  },
  argTypes: {
    title: {
      control: 'text',
      description: '标题内容，必填',
      type: { required: true },
    },
    list: {
      control: 'object',
      description: '历史记录列表',
      type: { required: true, summary: 'array' },
    },
  },
};

const Template = (args, { argTypes }) => ({
  components: { STrackingHistory },
  props: Object.keys(argTypes),
  template: '<STrackingHistory v-bind="$props" />',
});

export const Default = Template.bind({});
(Default as any).args = {
  title: 'Order Tracking History',
  list: [
    {
      time: '18:00:22',
      date: '2021-11-23',
      status: 'string; // 选填，缺省时不显示',
      statusType: 'default',
      contents: [
        {
          label: 'Message',
          value: 'LineContent[]; // 选填，按顺序展示每一行内容',
        },
        {
          label: 'Oprater',
          value: 'LineContent[]; // 选填，按顺序展示每一行内容',
        },
      ],
      splitLineText: 'New Order',
    },
    {
      date: '2021-1-2',
      status: 'string; // 选填，缺省时不显示',
      statusType: 'default',
      contents: [
        {
          label: 'Operator',
          value: 'LineContent[]; // 选填，按顺序展示每一行内容',
        },
      ],
    },
    {
      date: '2021-11-23',
      status: 'string; // 选填，缺省时不显示',
      contents: [
        {
          value: 'LineContent[]; // 选填，按顺序展示每一行内容',
        },
      ],
    },
    {
      date: '2021-11-23',
      status: 'string; // 选填，缺省时不显示',
      statusType: 'success',
      contents: [],
    },
    {
      date: '2021-1-23',
      contents: [{}],
    },
    {
      date: '2021-1-3',
    },
    {
      date: '2021-11-23',
      contents: [
        {
          label: 'Message',
        },
      ],
    },
  ],
};

2. docz

Docz is an efficient, zero-configuration event recording tool.

Docz based on MDX , there are many built-in components that can help you record your things.

At the same time, supports adding plug-ins Docz , so as to control many things through the 0609296db23f6b process and data.

Code example

// Button.mdx
import { Playground } from 'docz'
import { Button } from './Button'

# Button

## Basic usage

<Playground>
  <Button>Click me</Button>
  <Button kind="secondary">Click me</Button>
</Playground>

Rendering example

This is an example on the official website. It can be seen that the code example needs to be written in the Playground tag, which brings a problem. It is not possible to write the import module in the code example, which is actually not very friendly to developers.

Our SSC-UI-React component library uses docz , the actual effect:

3. dumi

dumi is a documentation tool for component development scenarios.

It is available out of the box, focusing on component development and documentation.

Based on TypeScript type definitions, component APIs, mobile component library writing and multi-language support are automatically generated.

Code example

In the type definition:

Rendering example

Overall comparison

The following is a comparison of the characteristics of the three libraries:

	docz	story book	dumi
Supported component library types	all ✅	all ✅	React Only
Lightweight / developer friendly	❌	❌	✅
The documentation is embedded in the component catalog	❌	✅	✅
Write the imported module in the code example	❌	❌	✅
Automatically generate component library API	❌	❌	✅
Support the writing of other types of documents besides component library documents	✅	✅	❌

In summary, I happily decided to React Pro Components component library document to dumi .

Summary of stepping on the pit

1. React version incompatibility issue

After a migration operation, we yarned a bit and found that an error was reported:

This is an error about react type checking reported by ts. At first, it was thought that there were too many ts checks. Then configure excluded: ['node-modules'] in tsconfig.json to remove this check, but it is still not easy to configure it. .

After a careful inspection, it is found in yarn.lock that the react version that the component library depends on is 16, and the react version that depends on is 1609296db241f4, and downloads the 17 version of react. Because the two versions of react have different ts types , Causing the type check to fail.

In this case, we only need to show that the version of the specified react is 16. 16 is in the range of *, and it will not cause dumi to have an error.

Add in package.json:

  "resolutions": {
    "@types/react": "^16.9.23"
  }

That's it.

2. Document citation issues

Since the dumi document is user-oriented, the method of introducing components when writing the document, for example:

For example, the Button component is:

import { EditArea } from 'react-pro-components'

node_module package is introduced here, the changes to the component library cannot be mapped to the document, and alias mapping needs to be added.

Add in .umirc.ts

const path = require('path');
const chainWebpack = require('webpack-chain');
export default {
    // 其他配置
  chainWebpack(memo) {
    // 设置 alias
    memo.resolve
      .alias
      .set('react-pro-components', path.resolve(__dirname, 'src', 'components'))
  },
};

3. Other issues

1. Does dumi support partial attribute hiding of api documents?

Not currently supported

1. Does dumi support search?

site mode is supported, doc mode is temporarily not supported.

1. dumi md file separately placed in a folder under the component directory?

Not currently supported, it needs to be placed directly in the component directory, such as the Button component:

├── Button
│   └── index.md

in conclusion

After much comparison, we migrated a React component library to dumi , and achieved good results.

dumi who need to do React component libraries can pay attention to 0609296db24442.

As for the Vue component document library, you can choose flexibly according to your own situation.

Hope this article can be helpful to everyone, thank you.

At last

If you find the content helpful, you can follow my official account, keep up with the latest developments, and learn together!

Related Links

1. https://zhuanlan.zhihu.com/p/110381664
2. https://storybook.js.org/docs/react/get-started/browse-stories
3. https://d.umijs.org/zh-CN