# 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-immerdynamicImport
, Whether to enable dynamic import, options same as #dynamicImport, and if you configure it in #dynamicImport, the options items will be inherited into dvahmr
, 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 isArray(RegExp)
, used to ignore certain routes, such as using dva, usually need to ignore the models, components, services, etc.update
, type isFunction
, 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_CNbaseNavigator: true
, // default true, when it is true, will usenavigator.language
overwrite defaultantd: true
, // use antd, default is truebaseSeparator: '-'
, // the separator betweenlang
andlanguage
, 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 nameloadingComponent
, Specify the component path at load timelevel
, 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
, Defaultsrc/manifest.json
workboxPluginMode
Workbox mode, Type:String
, DefaultGenerateSW
(generate a brand new Service Worker); orInjectManifest
(inject code to existed Service Worker)workboxOptions
Check Workbox Config for advanced usage. Few important options:swSrc
Type:String
, Defaultsrc/service-worker.js
, applicable only inInjectManifest
modeswDest
Type:String
, Defaults toservice-worker.js
or the same with basename inswSrc
if providedimportWorkboxFrom
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
Turn on the HD solution.
# fastClick
- Type
Boolean
Enable fastClick.
# title
- Type
String
orObject
Enable title plugin for set HTML title:
options include:
defaultTitle
: 'default tile', // required, when option type is String, will use option as the default titleformat
: '{parent}{separator}{current}', // default {parent}{separator}{current}, title formatseparator
: ' - ', // default ' - 'useLocale: true
, // default false, whether to uselocale
for multi-language support. If setuseLocale: true
, title displayed will be picked fromlocales/*.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 byumi
# 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