background

Some time ago, the department in the heat of all kinds of component library.

Component library, inevitably need to do component display and description, to use some documentation tools.

We have also tried several different documentation tools in our project. Today I would like to share some experiences with you, hoping that it will be helpful to you.

The body of the

Currently, we use three documentation tools for our component library, which are:

  1. Story Book
  2. Docz
  3. Dumi

I will compare these three tools and give some conclusions based on actual use.

1. Story Book

StoryBook provides a development environment for a set of UI components.

It allows you to browse component libraries, see the different states of each component, and develop and test components interactively. It currently supports front-end libraries and frameworks like React, VUE, Angular, and so on.

Code sample

// 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'};Copy the code

Storybooks provide components that can be written interactively, using template-.bind ({}) to bind components, and args to expose interactible properties.

The supported component libraries are rich, but the documentation needs to be compatible with interactive patterns in addition to providing examples.

Render the sample

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

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

export default {
  title: 'Design System/ display /TrackingHistory'.component: STrackingHistory,
  parameters: {
    docs: {
      description: {
        component: 'Order history tracking, mainly in terms of time and status',}},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: 'Title content, required'.type: { required: true}},list: {
      control: 'object'.description: 'History List'.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; // This is optional. By default, ' 'is not displayed..statusType: 'default'.contents: [{label: 'Message'.value: 'LineContent[]; // Show each row in order. '}, {label: 'Oprater'.value: 'LineContent[]; // Show each row in order. '],},splitLineText: 'New Order'}, {date: '2021-1-2'.status: 'string; // This is optional. By default, ' 'is not displayed..statusType: 'default'.contents: [{label: 'Operator'.value: 'LineContent[]; // Show each row in order. ',},],}, {date: '2021-11-23'.status: 'string; // This is optional. By default, ' 'is not displayed..contents: [{value: 'LineContent[]; // Show each row in order. ',},],}, {date: '2021-11-23'.status: 'string; // This is optional. By default, ' 'is not displayed..statusType: 'success'.contents: []}, {date: '2021-1-23'.contents: [] {}}, {date: '2021-1-3'}, {date: '2021-11-23'.contents: [{label: 'Message',},],},],},};Copy the code

2. docz

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

Docz is based on MDX and has many built-in components to help you keep track of your events.

It also supports adding plug-ins to make it easier to control many things through Docz processes and data.

Code sample

// 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>
Copy the code

Render the sample

This is an example from the official website, and you can see that the code sample needs to be written in the Playground tag, which leads to a problem: there is no way to write an introduction module in the code sample, which is actually not very developer-friendly.

Our SSC-UI-React component library uses Docz.

3. dumi

Dumi is a documentation tool for component development scenarios.

Out of the box, it focuses attention on component development and documentation.

Automatic component API generation, mobile component library writing, and multilanguage support based on TypeScript type definitions.

Code sample

In the type definition:

Render the sample

The overall contrast

Here is a comparison of the features of the three libraries:

docz story book dumi
Supported component library types written All ✅ All ✅ React Only
Lightweight/developer friendly ❌ ❌ ✅
The documentation is embedded in the component directory ❌ ✅ ✅
Write the import module in the code example ❌ ❌ ✅
Automatically generate component library apis ❌ ❌ ✅
Support for writing other types of documentation besides component library documentation ✅ ✅ ❌

In summary, it was happily decided to migrate the React Pro Components library documentation to Dumi.

Summary on pit

1. React version incompatibility

After a migration operation, we have a yarn check and find an error:

Tsconfig. json configuration excluded: [‘ nodes-modules ‘] removed this check, but it still doesn’t work.

After a close check, it is found that the Component library depends on the React version 16 in Yarn.Lock, while dumi depends on the react version *. The * version downloads the React version 17, because the two versions of react ts are different. The type check fails.

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

In package.json, add:

Resolutions: {"@types/react": "^16.9.23"}Copy the code

Can.

2. The document reference is faulty

Since dumi’s documentation is user-facing, it introduces component methods when writing the documentation, for example:

For example, the Button component is:

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

Since the package for node_module is being introduced, changes to the component library cannot be mapped to the document and alias mappings need to be added.

In.umirc.ts add:

const path = require('path');
const chainWebpack = require('webpack-chain');
export default {
	// Other configurations
  chainWebpack(memo) {
    / / set the alias
    memo.resolve
      .alias
      .set('react-pro-components', path.resolve(__dirname, 'src'.'components'))}};Copy the code

3. Other questions

  1. Does Dumi support partial attribute hiding in API documentation?

Temporary does not support

  1. Does Dumi support search?

Site mode is supported, doc mode is not supported.

  1. dumiIs the MD file in a separate folder in the component directory?

For example, Button component:

├ ─ ─Button│ └ ─ ─ the index.md
Copy the code

conclusion

After a lot of comparison, we moved a React component library to Dumi and got great results.

If you need to make a React component library, you can keep an eye on Dumi.

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

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

The last

If you think the content is helpful, you can follow my public number, grasp the latest developments, learn together! (Small egg with front skin)

A link to the

  1. zhuanlan.zhihu.com/p/110381664
  2. Storybook.js.org/docs/react/…
  3. d.umijs.org/zh-CN