background

At present, the department is promoting engineering construction and technology stack migration (Preact->React), so many old projects need to be reconstructed. Various UI components originally packaged are also dependent on Preact framework and exist in the form of separate NPM packages with different code styles and no unified UI component query platform. Based on this, We decided to build a unified LIBRARY of UI components.

The target

  • Component visualization (support for multi-platform H5/PC)

  • Automatic generation of API documents, less writing document work

Component documentation project research

  1. React Docgen

Official introduction:

React – DocGen is a CLI and toolkit that helps extract information from the React component and generate documentation from it. It parses the source into an AST using the AST type and @Babel/Parser, and provides methods for processing this AST to extract the desired information. The output/return value is a JSON BLOb /JavaScript object.

That is, it can extract some key information of the component, and we can convert this information into markDown, and finally generate the component description document based on this MarkDown. No component preview and lots of extra work, pass

  1. docz

This is a library that generates component documentation based on MDX files. You can automatically add MDX files inside each component and Docz will automatically convert them into a deployment generated documentation library. You still need to write your own MDX file, pass

  1. Storybook

  2. React Styleguidist

Storybook (STAR: 57.2k) and Styleguidist(React-Styleguidist Star: 9.5K) both support automatic generation of component documents. They support component preview, component interaction status display, and automatic generation of component API documents. Storybooks also have the following advantages over Styleguidist:

  1. Mobile preview is supported
  2. Framework to support more richer (the React/Vue/presents/Web Component/Ember/HTML/Mithril/Marko/Svelte/Riot/Preact/Rax/RN, etc.)

Design and development

  1. The storybook dependencies and plugins installed in our project are shown below. Storybook provides a rich market for plugins that enrich the component library platform.
"devDependencies": {
  "@storybook/addon-actions": "^ 6.0.28"."@storybook/addon-console": "^ 1.2.2." "."@storybook/addon-essentials": "^ 6.0.28"."@storybook/addon-links": "^ 6.0.28"."@storybook/addons": "^ 6.0.28"."@storybook/react": "^ 6.0.28"."@storybook/theming": "^ 6.0.28",}Copy the code
  1. After storyBook is installed, a.storybook folder will be added to the project, which contains some basic storybook configuration
// main.js storybook packages the build configuration file
module.exports = {
  // Need to package the build build document file folder
  stories: ['.. /src/**/*.stories.mdx'.'.. /src/**/*.stories.@(js|jsx|ts|tsx)'].// The third party addons to enable
  addons: ['@storybook/addon-links'.'@storybook/addon-essentials'].// Storybook already contains a basic WebPack configuration and supports custom configuration items
  webpackFinal: async (config) => {
    config.devtool = false;
    config.performance = {
      hints: false.maxEntrypointSize: 512000.maxAssetSize: 512000};returnconfig; }};// manager.js component library base theme style configuration file
import { addons } from '@storybook/addons';
import { create } from '@storybook/theming';

addons.setConfig({
  showRoots: true.theme: create({
    base: 'light'.brandUrl: '* * *'.// brandImage: 'https://y.qq.com/favicon.ico',
    brandTitle: 'QQ Music UI Component Library ',})});Copy the code
  1. Component development and documentation generation

Component directory structure

.├ ── avatar.stories.tsx ├─ indexCopy the code

Component entry file index.tsx

import * as React from 'react';
import { fixUrl } from '.. /libs/pic';

// Component Props definition, from which storybook generates API documentation (support PropsType)
export interface IAvatarProps {
  /** * Head size // This field describes the component parameter Description */
  size: number;
  /** ** avatar link */
  avatarUrl: string;
  /** * Alt attribute */altName? : string; }/** * You can also add component customization ** /
export const Avatar: React.FunctionComponent<IAvatarProps> = (props) = > {
  const { size = Avatar.defaultProps.size, avatarUrl, altName = Avatar.defaultProps.altName } = props;
  return (
    <img
      style={{ display: 'block', width: size.height: size.borderRadius: size }}
      src={fixUrl(avatarUrl)}
      alt={altName| | 'portrait'} / >
  );
};

// Component default parameters
Avatar.defaultProps = {
  size: 100.altName: 'avatar'};Copy the code

Storybook file A.c tories. TSX

import React from 'react';
import { Story, Meta } from '@storybook/react/types-6-0';
import { IAvatarProps, Avatar } from './index';

// Define component group/TAB name
export default {
  title: 'Data show /Avatar'.component: Avatar,
  argTypes: {},}as Meta;

// Component preview Demo, supporting multiple Demo preview
const Template: Story<IAvatarProps> = (args) = > <Avatar {. args} / >;

export constFace = Template. Bind ({}); Heads. Args = {size: 100.avatarUrl: 'https://y.gtimg.cn/music/photo_new/T001R150x150M000002lO5Lc1GCmvn_2.jpg'.altName: 'nickName'};Copy the code
  1. performyarn run storybookPreview effects directly in the browser, switch to the Canvas TAB bar, you can directly modify component parameters, component preview will be updated in real time.

  1. Add component library instruction documentation to support MDX documentation
// index.stories.mdx
import { Meta } from '@storybook/addon-docs/blocks';

// Set the group name
<Meta title="Introduction /Getting started" /># Getting Started ##`Input`Components are used as an exampleimport { Input } from '* * *';
Copy the code
  1. Document packaging and publishing

Running YARN Run build-storybook will generate the storybook-static document product in the root directory and publish the build product directly.