Plugin

How to use

Install the plugin npm package to the devDependencies of the project to enable the plugin, for example:

$ npm i @umijs/plugin-name -D

If the plug-in provides configuration items, please configure in config/config.ts or .umirc.ts, for example:

export default {
  // Other configuration items
  field: {},
};

Plugin list

Behind dumi is Umi. This means that most of the plugins in the Umi ecosystem can work with dumi.

Here is only a list of plugins that may be used in component development. For more plugins, please visit Umi's official document.

@umijs/plugin-analytics

• Introduction: Enable Google Analytics or Baidu Statistics for documents
• Configuration:

export default {
  analytics: {
    // Google Analytics code, will be enabled after configuration
    ga: 'google analytics code',
    // Baidu statistics code, will be enabled after configuration
    baidu: '5a66cxxxxxxxxxx9e13',
  },
};

For more information, please visit: Umi plugin - @umijs/plugin-analytics.

@umijs/plugin-sass

• Introduction: Enable Sass compilation support during component library development. Note that whether the plugin is enabled or not has nothing to do with the component library building tool (father-build). If the component library itself uses Sass, we also need to enable father-build Sass compilation support
• Configuration:

export default {
  sass: {
    // The default value is Dart Sass. If you want to use Node Sass instead, you can install the node-sass dependency and use this configuration item
    implementation: require('node-sass'),
    // The configuration item passed to Dart Sass or Node Sass can be a Function
    sassOptions: {},
  },
};

For more information, please visit: Umi plugin - @umijs/plugin-sass.

@umijs/plugin-esbuild

• Introduction: Use esbuild as the compressor of the document site product. It is an experimental feature and may have pits, but the compression speed effect is outstanding
• Configuration:

export default {
  esbuild: {}, // Enable esbuild compression
};

For more information, please visit: Umi plugin - @umijs/plugin-esbuild.

Plugin development

If the existing plugins cannot meet the needs, or you want to customize some behaviors of dumi, you can develop your own plug-in to achieve this, and create a plugin.ts in the project:

// /path/to/plugin.ts
import { IApi } from 'dumi';

export default (api: IApi) => {
  // Write plugin content
};

Then enable it in the dumi configuration file:

export default {
  plugins: ['/path/to/plugin.ts'],
};

Plugin API

The basic plugin API is provided by Umi and includes the following APIs.

In addition, in order to facilitate plugin developers to customize dumi's behavior, dumi provides the following plugin APIs.

dumi.getRootRoute

Used to get the root route of the document part in the routes configuration.

This API is only used to get routes. If you need to modify it, please use the modifyRoutes API below. Calling method:

// /path/to/plugin.ts
import { IApi } from 'dumi';

export default async (api: IApi) => {
  const rootRoute = await api.applyPlugins({
    key: 'dumi.getRootRoute',
    type: api.ApplyPluginsType.modify,
    initialValue: routes,
  });
};

dumi.modifyAssetsMeta

Used to modify the asset metadata produced by the dumi assets command.

If you don’t know what asset metadata is, you can visit Advanced - UI assets meta data.

This API is usually used to customize the asset metadata content of your team. For example, there is an internal service that automatically generates demo thumbnails.

You can use this method to modify the asset metadata that is finally entered into the npm package. Calling method:

// /path/to/plugin.ts
import { IApi } from 'dumi';
import IAssetsPackage from 'dumi-assets-types';

export default (api: IApi) => {
  api.register({
    key: 'dumi.modifyAssetsMeta',
    fn(pkg: IAssetsPackage) {
      // Process pkg and return new pkg
      return pkg;
    },
  });
};

dumi.detectCodeBlock

When dumi is parsing Markdown, if it finds a React code block, it will trigger this hook and pass in the code block information. Calling method:

// /path/to/plugin.ts
import { IApi } from 'dumi';
import { ExampleBlockAsset } from 'dumi-assets-types';

export default (api: IApi) => {
  api.register({
    key: 'dumi.detectCodeBlock',
    fn(block: ExampleBlockAsset) {
      // You can do statistics, storage, etc. on the block
    },
  });
};

dumi.detectAtomAsset

When dumi is parsing Markdown, if the corresponding component asset is detected, this hook will be triggered and the information of the component will be passed in.

For example, src/Button/index.tsx is a component asset. Calling method:

// /path/to/plugin.ts
import { IApi } from 'dumi';
import { AtomAsset } from 'dumi-assets-types';

export default (api: IApi) => {
  api.register({
    key: 'dumi.detectAtomAsset',
    fn(atom: AtomAsset) {
      // Statistics and storage of atom can be done
    },
  });
};

dumi.detectApi

When dumi is parsing Markdown, if it detects that it is automatically generated using API, this hook will be triggered and related API data will be transmitted. Calling method:

// /path/to/plugin.ts
import { IApi } from 'dumi';

export default (api: IApi) => {
  api.register({
    key: 'dumi.detectApi',
    fn({ identifier, data }) {
      // identifier is the API export identifier, data is the API attribute data
    },
  });
};

dumi.modifyThemeResolved

Used to modify the analysis result of dumi's theme package, usually used to customize unique theme behavior, such as adding built-in components through API. Calling method:

// /path/to/plugin.ts
import { IApi } from 'dumi';
import { IThemeLoadResult } from '@umijs/preset-dumi/lib/theme/loader';

export default (api: IApi) => {
  api.register({
    key: 'dumi.modifyThemeResolved',
    fn(resolved: IThemeLoadResult) {
      // Modify resolved and return
      return resolved;
    },
  });
};