An overview,

Last week, the component documents in the team were migrated from DOCz to Dumi, and the migration cost was about one to two days. Here I will give you a brief introduction to Dumi.

Component library documentation tools

This section will compare the following three component library documentation libraries that are widely used in the market to illustrate the reasons for the migration and the advantages of Dumi. If you don’t want to see it, you can skip it.

2.1 Comparison of writing methods

2.1.1 Docz

Docz is an efficient, zero-configuration event logging tool. Docz is based on MDX and has many built-in components to help you record your events. It also supports adding plug-ins to make it easier to manage many things through Docz processes and data.

2.1.1.1 Example

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

2.1.1.2 Rendering examples

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

2.1.2 storybook

Storybook is a UI component development environment that allows you to browse the component library, view the different states of each component, develop and test components interactively, and currently supports react, Vue, Angular and other front-end frameworks.

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

2.1.1.2 Rendering examples

Storybook provides interactive component writing, binding components through template.bind ({}), and exposing interactive properties through args. And the supported component library is rich, but the documentation needs to provide examples, but also compatible with interactive patterns.

2.1.3 dumi

Dumi is a documentation tool designed for component development scenarios. It has out-of-the-box focus on component development and documentation, automatic component API generation based on TypeScript type definitions, mobile component library writing, and multi-language support.

2.1.1.1 Example

In the index, md

import React from 'react';

export default() = ><h1>Hello dumi!</h1>;

<API />
Copy the code

In the type definition

export interface TemplateLinkProps {
  / * * *@description: component extra CSS className */
  templatePath: string;
  / * * *@description: I am a mandatory property */children? :any;
}
Copy the code

2.1.1.1 Rendering example

You can see that the API documentation is generated automatically.

2.2 Overall comparison

Here are the features of the three libraries:

In summary, it was a pleasure to decide to migrate the component library documentation to Dumi.

Three, step pit summary

3.1 ReactVersion incompatibility problem

After a migration operation, weyarnAfter a while, I found that the report was wrong.This is atsReported aboutreactType checking error, initially thought to betsMore tests, thentsconfig.jsonconfigurationExcluded: [' node - modules'], remove the check, but it still doesn’t work.

After a careful check, yarn.lock found that the component library relied on react version 16, while Dumi relied on React version *. * downloaded react version 17, because the TS type of the two versions was different. The type check fails.

React = 16; react = 16; react = 16;

Add this to package.json:

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

Can.

3.2 Document Reference Problems

For example, the Button component import {EditArea} from ‘react-pro-components’. Since node_module package is introduced here, This prevents changes to the component library from being mapped to the document, requiring the addition of an alias map.

Add to.umirc.ts:

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

Q & A

4.1 Is it supported to hide some attributes of API documents?

Temporary does not support

4.2 Is search supported?

The site mode is supported, but the doc mode is not.

4.3 Are md files placed in a separate folder under the component directory?

Not supported at the moment, need to put directly in the component directory, such as Button component:

├── ├─ exercisesCopy the code

= = = = = = = = = = = = = = = = = = = = = I’m show MOE line = = = = = = = = = = = = = = = = = = = = =