# umi-plugin-react

This is a collection of officially packaged plugins with 13 commonly used advanced features.

# Install

$ yarn add umi-plugin-react --dev

# Usage

Configured in .umirc.js:

export default {
  plugins: [
    [
      'umi-plugin-react',
      {
        dva: {
          immer: true,
        },
        antd: true,
        routes: {
          exclude: [/models\//],
        },
        polyfills: ['ie9'],
        locale: {},
        library: 'react',
        dynamicImport: {
          webpackChunkName: true,
          loadingComponent: './components/Loading.js',
        },
        dll: {
          exclude: [],
        },
        pwa: true,
        hd: true,
        fastClick: true,
        title: 'default title',
      },
    ],
  ],
};

# Configuration items

All features are turned off by default and will be enabled if there is a true value.

# dva

Type: Object

Based on umi-plugin-dva, see the details at Use with dva。

Configuration items includes:

immer, Whether to enable dva-immer
dynamicImport, Whether to enable dynamic import, options same as #dynamicImport, and if you configure it in #dynamicImport, the options items will be inherited into dva
hmr, Whether to enable dva hmr

WARNING

If there is a dva dependency in the project, the dependencies in the project are prioritized.

# antd

Type: Boolean

Automatically configure babel-plugin-import to enable on-demand compilation of antd, antd-mobile and antd-pro, with built-in antd and antd-mobile dependencies, There is no need to manually install in the project.

WARNING

If there is an ant or antd-mobile dependency in the project, the dependencies in the project are prioritized.

# routes

Type: Object

based on umi-plugin-routes, used to modify routes in batches.

options include:

exclude, type is Array(RegExp), used to ignore certain routes, such as using dva, usually need to ignore the models, components, services, etc.
update, type is Function, for update routes.

# polyfills (deprecated)

Type: Array(String)

Please use config.targets instead

Based on umi-plugin-polyfills, used to add polyfills.

Currently supports configuration of ['ie9'], ['ie10'] or ['ie11'] for quickly compatibility.

# locale

Type Object

Based on umi-plugin-locale and react-intl, used to resolve internationalization.

options include:

default: 'zh-CN', // default zh-CN, if baseSeparator set _，default zh_CN
baseNavigator: true, // default true, when it is true, will use navigator.language overwrite default
antd: true, // use antd, default is true
baseSeparator: '-', // the separator between lang and language, default -

# library

Type: String

It is possible to switch the underlying library to either preact or react.

# dynamicImport

Type: Object

Implement routing-level code splitting, which specifies which level of on-demand loading is required.

options include:

webpackChunkName, Whether to add a meaningful file name
loadingComponent, Specify the component path at load time
level, specifying the route level to code splitting

# dll

Type: Object

Increase the second startup speed by webpack dll plugin.

options include:

include
exclude

# hardSource

[hardSource] is no longer valid. Please remove it from the configuration file.

# pwa

Type Object

Enable some PWA features including:

Generate a manifest.json
Generate a Service Worker on PRODUCTION mode

options include:

manifestOptions Type: Object, includes following options:
- srcPath path of manifest, Type: String, Default src/manifest.json
workboxPluginMode Workbox mode, Type: String, Default GenerateSW(generate a brand new Service Worker); or InjectManifest(inject code to existed Service Worker)
workboxOptions Check Workbox Config for advanced usage. Few important options:
- swSrc Type: String, Default src/service-worker.js, applicable only in InjectManifest mode
- swDest Type: String, Defaults to service-worker.js or the same with basename in swSrc if provided
- importWorkboxFrom Type: String，Workbox loads from Google CDN by default, you can choose to 'local' mode which will let Workbox loads from local copies

You can refer to Workbox for more API usages.

Here's a simple example:

// .umirc.js or config/config.js
export default {
  pwa: {
    manifestOptions: {
      srcPath: 'path/to/manifest.webmanifest',
    },
    workboxPluginMode: 'InjectManifest',
    workboxOptions: {
      importWorkboxFrom: 'local',
      swSrc: 'path/to/service-worker.js',
      swDest: 'my-dest-sw.js',
    },
  },
};

You can also listen to some CustomEvent when Service Worker has updated old contents in cache. It's the perfect time to display some message like "New content is available; please refresh.". For example, you can listen to sw.updated event in such UI component:

window.addEventListener('sw.updated', () => {
  // show message
});

window.addEventListener('sw.registered', e => {
  // e.detail.update()  // trigger a manual update
  // Configure the appropriate polling and match the sw.updated event, without the user refreshing or opening a new tab to update.
});

You can also react to network environment changes, such as offline/online:

window.addEventListener('sw.offline', () => {
  // make some components gray
});

sw.* Events are synchronized with events in register-service-worker. For more usage, please refer to the link above.

# hd

Type Boolean or Object

Turn on the HD solution, by default, follow the 750px design draft (1rem=100px).

// .umirc.js or config/config.js
export default {
  hd: true,
};

hd: true equipped to the following configuration:

// .umirc.js or config/config.js
export default {
  // equipped to hd: true
  hd: {
    theme: {
      // antd-mobile HD solution
      '@hd': '2px',
    },
    // more: https://github.com/pigcan/postcss-plugin-px2rem#configuration
    px2rem: {
      rootValue: 100,
      minPixelValue: 2,
    },
  }
};

At the same time, you can customize the adaptation scheme:

// default, 750px design draft
// src/hd.(tsx|ts|js|jsx)
import vw from 'umi-hd/lib/vw';
import flex from 'umi-hd/lib/flex';

// Fix document undefined when ssr. #2571
if (typeof document !== 'undefined') {
  if (document.documentElement.clientWidth >= 750) {
    vw(100, 750);
  } else {
    flex();
  }

  // hd solution for antd-mobile@2
  // ref: https://mobile.ant.design/docs/react/upgrade-notes-cn#%E9%AB%98%E6%B8%85%E6%96%B9%E6%A1%88
  document.documentElement.setAttribute('data-scale', true);
}

# fastClick

Type Boolean

Enable fastClick, solve the prevent the 300ms click delay on mobile devices.

# title

Type String or Object

Enable title plugin for set HTML title:

options include:

defaultTitle: 'default tile', // required, when option type is String, will use option as the default title
format: '{parent}{separator}{current}', // default {parent}{separator}{current}, title format
separator: ' - ', // default ' - '
useLocale: true, // default false, whether to use locale for multi-language support. If set useLocale: true, title displayed will be picked from locales/*.js

When the title plugin is enabled you can configure the title in the route configuration or in the page component in pages folder.

For example, with configuration file:

// .umirc.js or config/config.js
export default {
  routes: [
    {
      path: '/testpage',
      component: './testpage',
      title: 'test page',
    },
  ],
};

or with convensional routing

/**
 * title: test page
 */
export default () => {
  return <div>testpage</div>;
};

title/route configuration must be at the top of the routing page component, otherwise it will be ignored by umi

# customized document.ejs

If you defined src/pages/document.ejs by your own, please make sure the snippet <title><%= context.title %></title> is added, otherwise the title.defaultTitle will not be injected to the generated index.html

# chunks

Type：Array(String)

default: ['umi'], modifiable，e,g: require to load vendors.js before umi.js if split code into vendor chunk

Example:

// .umirc.js or config/config.js
export default {
  chainWebpack: function (config, { webpack }) {
    config.merge({
      optimization: {
        minimize: true,
        splitChunks: {
          chunks: 'all',
          minSize: 30000,
          minChunks: 3,
          automaticNameDelimiter: '.',
          cacheGroups: {
            vendor: {
              name: 'vendors',
              test({ resource }) {
                return /[\\/]node_modules[\\/]/.test(resource);
              },
              priority: 10,
            },
          },
        },
      }
    });
  },
  plugins: [
    ['umi-plugin-react', {
        chunks: ['vendors', 'umi']
    }]
}

# scripts

Type：Array(Object) or Array(String)

Replace in <body>, after umi.js, use <%= PUBLIC_PATH %> specifies the publicPath

# headScripts

Type：Array(Object) or Array(String)

Replace in <head>, before umi.js, use <%= PUBLIC_PATH %> specifies the publicPath

# metas

Type：Array(Object)

# links

Type：Array(Object)

Use <%= PUBLIC_PATH %> specifies the publicPath

← Plugin @umijs/plugin-prerender →