Design and Implementation of a Taro Component Library with Integrated Documentation and Demo

Background

As the Mini‑Program business iterates, the number of components grows, leading to unclear component planning, low reuse, duplicate components, and tangled code. Clear documentation is essential to reduce communication costs and avoid fragmented development.

Solution Choice

Existing documentation frameworks such as dumi or VitePress work well for PC/H5, but there is no mature solution for Taro. The official taro‑ui lacks sufficient components and its examples do not match the documentation, increasing the learning curve. Therefore, a custom component library is built manually.

Main Module Technology Stack

Component: ES module output, on‑demand loading, built with Rollup; components are written in React using hooks, TypeScript, and Less.

Demo: Because Taro runs in a browser for documentation, a separate demo project using Taro React and H5 build is created. A custom webpack‑chain loader reads Markdown files and injects the demo code.

Documentation: Static pages built with Vite; Markdown rendered via react‑markdown; demo preview loaded in an iframe.

Directory Structure

├─config
│   ├─vite // vite configuration
│   └─rollup // rollup configuration
├─dist // documentation build output
├─docs-dist // doc build output
├─packages
│   ├─demo // component Taro demo project
│   ├─doc // API documentation project
│   └─ui // component library
├─tests
├─index.html // doc entry file
└─package.json

Development Process & Routing Relationship

Example: adding a tag component.

Create packages/ui/components/tag with entry tag/index.tsx and documentation tag/README.md . The built artifact is dist/tag/index.js .

Add a route /tag in the doc project; the route loads tag/README.md via Vite’s ?raw import and renders it with react‑markdown .

The demo project runs independently as an H5 page, embedded in an iframe. When the doc route changes, the iframe URL syncs and loads the corresponding demo page.

A custom markdown‑loader reads the example code from tag/README.md . Webpack alias @hb/rent-taro-components points to the built component dist/tag/index.js .

The loader aggregates all example code into a runnable page for live preview.

Architecture Advantages

Documentation and demo are generated from a single Markdown file, simplifying maintenance.

Each demo is isolated, keeping code clean and independent.

The right‑hand demo project can be released as a separate Mini‑Program if needed.

No black‑box modules; each part is transparent, making future maintenance easy.

Module Details

doc

Directory structure:

src
│   ├─components
│   │   ├─markdown-render // renders .md files
│   │   └─... // other layout components
│   ├─guides // guide documents
│   ├─router
│   │   ├─comp-doc.ts // component routes
│   │   ├─guide-doc.ts // guide routes
│   │   └─index.ts // export
│   ├─app.less
│   └─App.tsx // main page
└─main.tsx // entry

Example comp-doc.ts :

import Button from '@ui/button/README.md?raw';
import Tag from '@ui/tag/README.md?raw';

const compRoutes = [
  {
    name: '基础组件',
    path: '/basic',
    children: [
      { name: '按钮', path: '/button', component: Button },
      { name: '标签', path: '/tag', component: Tag },
    ],
  },
];

export default compRoutes;

demo

Directory structure (standard Taro project with a custom loader):

config
│   ├─dev.js
│   ├─index.js // Taro webpack config
│   ├─markdownloader.js // custom md loader
│   └─prod.js
src
│   ├─pages
│   │   └─basic
│   │       ├─button
│   │       │   ├─index.config.ts
│   │       │   └─index.tsx
│   │       └─tag
│   ├─app.config.ts // route config
│   ├─app.less
│   ├─app.ts
│   └─index.html
└─package.json

Key app.config.ts snippet (routes correspond one‑to‑one with doc routes):

export default {
  pages: [
    'pages/basic/button/index', // matches doc route /button
    'pages/basic/tag/index',
  ],
  ...
};

Page example pages/basic/button/index.tsx (imports the Markdown as a component):

// Directly import the component library README.md as a demo component
import Demo from '@components/button/README.md';

export default Demo;

Custom webpack chain in config/index.js to add the markdown loader:

const config = {
  h5: {
    // ...
    webpackChain(chain, webpack) {
      chain.merge({
        module: {
          rule: {
            mdLoader: {
              test: /\.md$/,
              use: [
                { loader: 'babel-loader', options: {} },
                { loader: `${path.join(__dirname, './markdownLoader.js')}`, options: {} },
              ],
            },
          },
        },
      });
    },
    // ...
  },
};

TypeScript & Rollup Configuration

Rollup uses rollup-plugin-typescript2 :

import RollupTypescript from 'rollup-plugin-typescript2';
// ...
plugins: [
  // ...
  RollupTypescript({ tsconfig: resolveFile('config/tsconfig.rollup.json') }),
];

On‑demand loading and multi‑entry build:

const inputD = {};
compFiles.forEach(item => {
  const val = item.replace(cwd, '')
    .replace('/packages/ui/src/components/', '')
    .replace('/index.tsx', '');
  inputD[`${val}`] = item;
});

const config = {
  input: inputD,
  plugins: [
    RollupPostCss({
      use: [['less', { javascriptEnabled: true }]],
      extract: 'index.less',
      extensions: ['.css', '.less'],
    }),
    RollupCopy({
      verbose: true,
      targets: [{ src: resolveFile('/packages/ui/src/components/*/*.less'), dest: resolveFile('/dist/styles') }],
    }),
  ],
};

This architecture provides a clear, maintainable, and extensible solution for a Taro component library with synchronized documentation and live demos.