Configuration
For the custom configurations available in umi, you can use the .umirc.ts
file or config/config.ts
in the project root directory. It's noteworthy that both files have the same functionality, just residing in different directories. You have to choose one of them, with .umirc.ts
having a higher priority.
For more information about the directory structure, you can learn more here.
umi's configuration file is a regular node module, which is used when the umi command line is executed and is not included in the browser-side build.
For some configurations that are required for the browser-side build, and some configurations that affect the style presentation, in umi they are collectively referred to as "runtime configuration", you can see more about it in runtime configuration.
Here is the simplest example of an umi configuration file:
import { defineConfig } from 'umi';export default defineConfig({outputPath: 'dist',});
Wrapping configurations with defineConfig
is to get better spell check support when writing the configuration file. If you don't need it, export default {}
works too.
It's important to note that when using umi, you don't need to understand the purpose of each configuration. You can briefly browse through all the configurations that umi supports below, and then, when needed, come back to see how to enable and modify the configurations you need.
For convenience, the following configurations are sorted alphabetically.
alias
- Type:
Record<string, string>
- Default value:
{}
Configure aliases, to map the source in import statements.
For example:
{alias: {foo: '/tmp/to/foo',}}
Then in the code, import 'foo'
will actually become import '/tmp/to/foo'
.
Some tips:
- It's better to use absolute paths as the value of alias, especially when pointing to a dependency, remember to add
require.resolve
, for instance,
// ❌{alias: {foo: 'foo',}}// ✅{alias: {foo: require.resolve('foo'),}}
- If you don't want subpaths to be mapped as well, remember to add a
$
suffix, for example
// import 'foo/bar' will be mapped to import '/tmp/to/foo/bar'{alias: {foo: '/tmp/to/foo',}}// import 'foo/bar' will still be import 'foo/bar', and won't be modified{alias: {foo$: '/tmp/to/foo',}}
autoprefixer
- Type:
object
- Default value:
{ flexbox: 'no-2009' }
Used for parsing CSS and adds vendor prefixes to CSS rules using values from Can I Use. It enables autoprefixing, such as automatically adding -webkit-
prefix.
For more configurations, please consult autoprefixer's options.
analyze
- Type:
object
- Default value:
{}
Specific configuration options for the analyzer plugin when analyzing product composition through the ANALYZE
environment variable. See webpack-bundle-analyzer
When using Vite mode, in addition to customizing the configuration of rollup-plugin-visualizer, excludeAssets
, generateStatsFile
, openAnalyzer
, reportFilename
, reportTitle
options will automatically adapt.
base
- Type:
string
- Default value:
/
To deploy the umi project in a non-root directory, you can use the base configuration.
The base configuration allows you to set a routing prefix for your application. For example, with routes /
and /users
, after setting base to /foo/
, you can access the previous routes through /foo/
and /foo/users
.
Note: The base configuration must be set at build time and can't be changed without rebuilding, because this value is inlined in the client-side package.
cacheDirectoryPath
- Type:
string
- Default value:
node_modules/.cache
By default, Umi stores some cache files generated during the build process in the node_modules/.cache
directory, such as logger logs, webpack cache, mfsu cache, etc. You can modify Umi's cache file directory using the cacheDirectoryPath
configuration.
Example,
// Change the cache file path to the node_modules/.cache1 foldercacheDirectoryPath: 'node_modules/.cache1',
chainWebpack
- Type:
(memo, args) => void
- Default value:
null
To extend Umi's built-in webpack configuration, we provide a way to modify the webpack configuration in a chained programming style, based on webpack-chain. See the documentation of webpack-api for specific APIs.
As shown below:
export default {chainWebpack(memo, args) {return memo;},};
This function has two parameters:
memo
is the existing webpack configurationargs
contains some additional information and auxiliary objects, currently includingenv
andwebpack
.env
is the current environment, with values ofdevelopment
orproduction
;webpack
is the webpack object, from which webpack's built-in plugins can be obtained.
Usage example:
export default {chainWebpack(memo, { env, webpack }) {// Set aliasmemo.resolve.alias.set('foo', '/tmp/to/foo');// Add extra pluginsmemo.plugin('hello').use(Plugin, [...args]);// Delete Umi's built-in pluginmemo.plugins.delete('hmr');},};
clickToComponent
- Type:
{ editor?: string }
- Default value:
false
Currently, only React projects are supported.
When this feature is enabled, you can jump to the source code location in the editor by Option+Click/Alt+Click
on the component. Option+Right-click/Alt+Right-click
opens the context to view the parent component.
About parameters. The editor
parameter defaults to 'vscode', supporting vscode
& vscode-insiders
.
Configure the behavior of clickToComponent, for more details see click-to-component.
Example:
// .umirc.tsexport default {clickToComponent: {},};
clientLoader
- Type:
{}
- Default value:
false
When enabled, you can declare a data loading function clientLoader
for each route. Extracting the data loading process required by the page into clientLoader
allows Umi to preload the data before the page components are fully loaded, avoiding the issue of waterfall requests. For details, see Route Data Preloading.
Example:
// .umirc.tsexport default {clientLoader: {},};
Configuration enabled, use in the route component:
// pages/.../some_page.tsximport { useClientLoaderData } from 'umi';export default function SomePage() {const { data } = useClientLoaderData();return <div>{data}</div>;}export async function clientLoader() {const data = await fetch('/api/data');return data;}
codeSplitting
- Type:
{ jsStrategy: 'bigVendors' | 'depPerChunk' | 'granularChunks'; jsStrategyOptions: {} }
- Default value:
null
Provide code splitting strategy solutions.
bigVendors is the big vendors scheme, which packs the files under node_modules in the async chunk together, which can avoid repetition. At the same time, the disadvantages are, 1) the size of a single file is too large, 2) there is no caching efficiency to speak of.
depPerChunk is similar to bigVendors, but different in that dependencies are split by package name + version, solving bigVendors’ issues with size and caching efficiency. However, it also brings potential problems, possibly leading to more requests. My understanding is that for non-large projects its actually fine because, 1) a single page's requests will not include a very large number of dependencies, 2) based on HTTP/2, dozens of requests are not a problem. But, for large or huge projects, a more suitable solution is needed.
granularChunks take a middle value between bigVendors and depPerChunk, while also having better utilization of caching efficiency. Unless there are special circumstances, the granularChunks strategy is recommended.
conventionLayout
- Type:
boolean
- Default value:
undefined
src/layouts/index.[tsx|vue|jsx|js]
is conventionally set as layout, enabled by default. It can be disabled by setting conventionLayout: false
.
conventionRoutes
- Type:
{ base: string; exclude: RegExp[] }
- Default value:
null
Modify the default convention-based route rules, only valid when using umi's convention-based routing. Convention-based routing, also known as file-based routing, means that you don’t need to write configurations manually, as the file system is the routes, and the routing configuration is analyzed through directories and files and their naming.
When using convention-based routing, it's conventioned that all (j|t)sx?
files under src/pages
are routes.
You can see more details in Convention-based Routing.
base
base
is used to set the base path for the routes by convention, by default reading from src/pages
. If it is a site for documentation, you might need to change it to ./docs
;
exclude
You can use exclude
to filter some files that are not needed, such as you can use it to exclude files under components, models, etc.
Example,
// Do not recognize files under components and models directories as routesconventionRoutes: {exclude: [/\/components\//, /\/models\//],}
copy
- Type:
Array<string | { from: string; to: string; }>
- Default value:
[]
Configure the files or folders to be copied to the output directory.
When configuring as a string, it is copied to the product directory by default, such as:
copy: ['foo.json', 'src/bar.json']
Will produce the following product structure:
+ dist- bar.json- foo.json+ src- bar.json- foo.json
You can also configure the specific copy location through objects, where the relative path starts from the project root directory:
copy: [{ from: 'from', to: 'dist/output' },{ from: 'file.json', to: 'dist' }]
This time will produce the following product structure:
+ dist+ output- foo.json- file.json+ from- foo.json- file.json
crossorigin
- Type:
{ includes?: string[] }
- Default value:
false
Configure the script tag's crossorigin. If declared, the local script will have a crossorigin="anonymous" attribute.
Regarding the parameters. The parameter includes
can allow extra non-local script tags to have this attribute.
For example:
crossorigin: {}
Then the output HTML will have these changes,
-<script src="/umi.js"></script>+<script src="/umi.js" crossorigin="anonymous"></script>
cssMinifier
- Type:
string
, optional values:esbuild
,cssnano
,parcelCSS
,none
- Default value:
esbuild
Configure the tool for minifying CSS during build time; none
means not to minify.
Example:
{cssMinifier: 'esbuild'}
cssMinifierOptions
- Type:
object
- Default value:
{}
Options for the CSS minification tool, cssMinifier
.
Example:
{cssMinifier: 'esbuild',cssMinifierOptions: {minifyWhitespace: true,minifySyntax: true,},}
Consult the corresponding documentation for CSS minification configuration.
cssPublicPath
- Type:
string
- Default value:
./
Customize the public path for external resources like images and files in CSS. Acts similar to publicPath
. The default value is ./
.
cssLoader
- Type:
object
- Default value:
{}
Configure css-loader , see css-loader > options
cssLoaderModules
- Type:
object
- Default value:
{}
Configure the behavior of CSS modules, see css-loader > modules.
For example:
cssLoaderModules: {// Configure to use camelCaseexportLocalsConvention: 'camelCase'}
deadCode
- Type:
{ patterns?: string[]; exclude?: string[]; failOnHint?: boolean; detectUnusedFiles?: boolean; detectUnusedExport?: boolean; context?: string }
- Default value:
false
Check for unused files and exports, only enabled at build phase.
For example:
deadCode: {}
Then execute build, if any issues are found, a warning will be printed:
Warning: There are 1 unused files:1. /pages/index.module.lessPlease be careful if you want to remove them (¬º-°)¬.
Configuration items:
patterns
: Scope of code identification, such as['src/pages/**']
exclude
: Scope to exclude from detection, such as['src/pages/utils/**']
failOnHint
: Whether to stop the process if detection fails, defaultfalse
not to stopdetectUnusedFiles
: Whether to detect unused files, defaulttrue
for detectiondetectUnusedExport
: Whether to detect unused exports, defaulttrue
for detectioncontext
: The directory to start matching, default as the current project root directory
define
- Type:
Record<string, string>
- Default value: As shown below
{'process.env.NODE_ENV' : process.env.NODE_ENV,'process.env.HMR' : process.env.HMR,'process.env.SOCKET_SERVER': process.env.ERROR_OVERLAY'}
Set available variables in the code based on define-plugin plugin.
🚨
- Property values will be converted with
JSON.stringify
. - The replacement of key values is matched by their syntactic form, for instance, configuring
{'a.b.c': 'abcValue'}
can't replace the code ina.b?.c
.
For example,
define: { FOO: 'bar' }
Then the code like console.log(hello, FOO)
will be compiled to console.log(hello, 'bar')
.
When you use these variables in a TypeScript project, you need to declare the variable type in the typings file to support ts type hints, for example:
If your typings file is global:
// typings.d.tsdeclare const FOO: string;
If your typings file is non-global (contains import/export):
// typings.d.tsimport './other.d.ts';declare global {const FOO: string;}
devtool
- Type:
string
- Default value: Dev defaults to
cheap-module-source-map
, no sourcemap by default for build
Sets the sourcemap generation method.
Common optional values include:
eval
, the fastest type, but does not support old browserssource-map
, the slowest but most comprehensive type
Example,
// Disable sourcemap generation in dev stagedevtool: false;// Only set sourcemap for dev stagedevtool: process.env.NODE_ENV === 'development' ? 'eval' : false;
classPropertiesLoose
- Type:
object
- Default value:
{}
Set babel class-properties to enable loose mode
esbuildMinifyIIFE
- Type:
boolean
- Default value:
false
Fix the namespace conflict caused by global variables automatically introduced by the esbuild compressor.
Since Umi 4 defaults to using esbuild as the compressor, the compressor will automatically inject global variables as polyfill, which may cause conflicts like async chunks global variables, conflicts between qiankun sub-apps and main apps' global variables, etc. This issue can be resolved by enabling this option or switching the jsMinifier
compressor.
For more details, see vite#7948.
Example,
esbuildMinifyIIFE: true
externals
- Type:
Record<string, string> | Function
- Default value:
{}
Set which modules are not to be bundled, instead to be imported through <script>
or other methods, usually used in conjunction with headScripts configuration.
Example,
// external reactexternals: { react: 'React' },headScripts: ['https://unpkg.com/react@17.0.1/umd/react.production.min.js'],
Note: Do not easily set antd’s externals, as due to its many dependencies and complicated usage, many problems could occur, and it’s hard to fully explain in one or two sentences.
extraBabelIncludes
- Type:
Array<string | RegExp>
- Default value:
[]
Configures extra NPM packages or directories for Babel compilation. For example:
export default {extraBabelIncludes: [// Support absolute pathjoin(__dirname, '../../common'),// Support npm package'react-monaco-editor',// Transpile all paths containing @scope/@scope/],};
extraBabelPlugins
- Type:
string[] | Function
- Default value:
[]
Configures extra babel plugins. Can pass the plugin address or plugin function.
extraBabelPresets
- Type:
string[] | Function
- Default value:
[]
Configures extra babel plugin sets. Can pass the plugin set address or plugin set function.
extraPostCSSPlugins
- Type:
PostCSSPlugin[]
- Default value:
[]
Configures extra postcss
exportStatic
- Type:
{ extraRoutePaths: IUserExtraRoute[] | (() => IUserExtraRoute[] | Promise<IUserExtraRoute[]>), ignorePreRenderError: boolean }
- Default:
undefined
When enabled, HTML files will be generated separately for each route, typically used for static site hosting. For example, if a project has the following routes:
//docs/docs/a
Without exportStatic
enabled, it will output:
dist/index.html
With exportStatic
enabled, it will output:
dist/index.htmldist/docs/index.htmldist/docs/a/index.html
Additional pages can be generated through the extraRoutePaths
sub-configuration, typically used for static generation of dynamic routes. For example, with the following route:
/news/:id
By default, it will only output dist/news/:id/index.html
, but you can staticize it through extraRoutePaths
configuration:
// .umirc.tsexport default {exportStatic: {// Configure fixed valuesextraRoutePaths: ['/news/1', '/news/2'],// Can also configure a function for dynamic retrievalextraRoutePaths: async () => {const res = await fetch('https://api.example.com/news');const data = await res.json();return data.map((item) => `/news/${item.id}`);},},}
The output files will then become:
dist/news/:id/index.htmldist/news/1/index.htmldist/news/2/index.html
In addition to supporting string data configuration, extraRoutePaths
can also be configured as an object array, used when SSR is enabled but you want to disable pre-rendering for certain routes, for example:
// .umirc.tsexport default {exportStatic: {// Output additional page files but skip pre-renderingextraRoutePaths: [{ path: '/news/1', prerender: false }],},}
When exportStatic
is used with ssr
, pre-rendering will be performed. If pre-rendering fails, an exception will be thrown and the build will be terminated. You can configure ignorePreRenderError
to ignore pre-rendering failure errors, for example:
// .umirc.tsexport default {exportStatic: {// Ignore pre-rendering failure errorsignorePreRenderError: true,},}
favicons
- Type:
string[]
- Default:
null
By default, the site will use the conventional favicon
to create icon meta head tags.
You can customize it like this:
favicons: [// Complete URL'https://domain.com/favicon.ico',// This will point to `/favicon.png`, make sure your project has `public/favicon.png`'/favicon.png']
forget
- Type:
{ ReactCompilerConfig: object }
- Default:
null
Whether to enable React Compiler (React Forget) functionality. Reference https://react.dev/learn/react-compiler.
forget: {ReactCompilerConfig: {},},
Note:
- forget is currently incompatible with mfsu and mako. If forget is enabled while mfsu or mako is on, an error will be thrown.
- forget requires react 19. When using it, please manually install react@rc and react-dom@rc as project dependencies.
forkTSChecker
- Type:
object
- Default:
null
Enable TypeScript type checking. Based on fork-ts-checker-webpack-plugin, configuration options can be found in fork-ts-checker-webpack-plugin's Options.
hash
- Type:
boolean
- Default:
false
Enable hash mode to include hash suffixes in build artifacts. Typically used for incremental releases and avoiding browser cache loading.
When enabled, the output typically looks like this:
+ dist- logo.sw892d.png- umi.df723s.js- umi.8sd8fw.css- index.html
Note: HTML files never have hash suffixes.
headScripts
- Type:
string[] | Script[]
- Default:
[]
Configure additional scripts in the <head>
.
For example:
headScripts: [`alert(1);`, `https://a.com/b.js`],
Will generate HTML:
<script>alert(1);</script><script src="https://a.com/b.js"></script>
If additional attributes are needed, switch to object format, for example:
headScripts: [{ src: '/foo.js', defer: true },{ content: `alert('hello');`, charset: 'utf-8' },],
helmet
- Type:
boolean
- Default:
true
Configure the integration of react-helmet-async
. When set to false
, react-helmet-async
will not be integrated, and you won't be able to import { Helmet }
from the framework. The build artifacts will also be reduced by the corresponding size.
history
- Type:
{ type: 'browser' | 'hash' | 'memory' }
- Default:
{ type: 'browser' }
Set the routing history type.
historyWithQuery
- Type:
{}
- Default:
false
Let history carry query parameters. For navigation scenarios using useNavigate
, you'll need to handle the query manually.
https
- Type:
{ cert: string; key: string; hosts: string[]; http2?: boolean }
- Default:
{ hosts: ['127.0.0.1', 'localhost'] }
Enable HTTPS mode for development. Umi 4 uses mkcert
by default to quickly create certificates. Please ensure it's installed.
About the parameters:
cert
andkey
are used to specify the cert and key files respectively.hosts
specifies which hosts should support HTTPS access, default is['127.0.0.1', 'localhost']
.http2
specifies whether to use HTTP 2.0 protocol, default is true (using HTTP 2.0 in Chrome or Edge browsers occasionally results inERR_HTTP2_PROTOCOL_ERROR
, if encountered, it's recommended to set this to false).
Example:
https: {}
icons
- Type:
{ autoInstall: {}; alias: Record<string,string>; include: Array<string>; }
- Default:
false
You can quickly reference icon sets or local icons through the Icon component exported by umi.
Using Icon Sets
In the umi configuration file, enable the icons feature and allow automatic installation of icon libraries.
icons: { autoInstall: {} },
Usage in pages:
import { Icon } from 'umi';<Icon icon="fa:home" />
The string in icon is a combination of collection:icon
, separated by :
. Icon sets are recommended to be searched on the Icônes website.
Using Local Icons
In the umi configuration file, enable the icons feature.
icons: {},
To use local svg icons, you need to save the svg files in the src/icons
directory, then reference them using the local
prefix. For example, if you have a umi.svg
in the src/icons
directory, you can reference it like this:
import { Icon } from 'umi';<Icon icon="local:umi" />
Configuration Options
autoInstall
indicates whether to automatically install icon sets; tnpm/cnpm clients are not currently supported, but you can manually install corresponding icon set packages@iconify-json/collection-name
. Reference: Icon Collection List, collection-name is the Icon set prefix item in the list.alias
is used to configure icon aliases. For example, after configuringalias:{home:'fa:home'}
, you can use thefa:home
icon throughicon="home"
.include
configures icons that need to be forcibly used, for exampleinclude: ['fa:home', 'local:icon']
. Common use cases: when icon strings are defined in a map, making them undetectable; when using theIcon
component inmdx
.
Icon Component Properties
- icon: specify the icon
- width: svg width
- height: svg height
- viewBox: svg viewBox
- style: external container style
- className: external container class name
- spin: whether to auto-rotate
- rotate: configure rotation angle, supports multiple formats like
1
,"30deg"
,"25%"
- flip: supports
vertical
,horizontal
, or their combinationvertical,horizontal
ignoreMomentLocale
- Type:
boolean
- Default:
true
Ignore moment's locale files to reduce build size.
Note: This feature is enabled by default. Configure ignoreMomentLocale: false
to disable it.
inlineLimit
- Type:
number
- Default:
10000
(10k)
Configure the threshold for whether image files should be base64 encoded. By default, files less than 10000 bytes will be compiled to base64 encoding, otherwise, they will be generated as separate files.
jsMinifier (webpack)
- Type:
string
, optional values:esbuild
,terser
,swc
,uglifyJs
,none
- Default:
esbuild
Configure the tool for minifying JavaScript during build; none
means no minification.
Example:
{jsMinifier: 'esbuild'}
jsMinifierOptions
- Type:
object
- Default:
{}
Options for jsMinifier
; by default, code minification will remove comments in the code, you can preserve comments through the corresponding jsMinifier
options.
Example:
{jsMinifier: 'esbuild',jsMinifierOptions: {minifyWhitespace: true,minifyIdentifiers: true,minifySyntax: true,}}
Configuration options need to correspond with the tool being used, refer to the respective documentation:
lessLoader
- Type:
object
- Default:
{ modifyVars: userConfig.theme, javascriptEnabled: true }
Configure less-loader's Options. See less-loader's Options for specific details.
The default version is less@4. If you need compatibility with less@3, please configure using less-options-math.
legacy
- Type:
{ buildOnly?: boolean; nodeModulesTransform?: boolean; checkOutput?: boolean; }
- Default:
false
When you need to support older browsers, you might need this option. When enabled, it will use non-modern build tools by default, which will significantly increase your build time.
legacy: {}
By default, it only takes effect during build. You can disable this restriction by setting buildOnly: false
.
You can enable the checkOutput: true
option to automatically run es-check
after each build to check if the .js
files in the output are in es5 format.
When this option is enabled:
- Custom
srcTranspiler
,jsMinifier
,cssMinifier
options are not supported. - All source code in
node_modules
will be transpiled, withtargets
compatible down to ie 11. You can disable the transformation ofnode_modules
by specifyingnodeModulesTransform: false
. In this case, you can useextraBabelIncludes
to more precisely transform packages with compatibility issues. - Since older browsers don't support Top level await, when using
externals
, make sure you're not using asynchronousexternalsType
while using synchronous dependency imports.
links
- Type:
Link[]
- Default:
[]
Configure additional link tags.
Example:
links: [{ href: '/foo.css', rel: 'preload' }],
4.3.2+
mako- Type:
{ plugins?: Array<{ load?: ((...args: any[]) => unknown) | undefined; generateEnd?: ((...args: any[]) => unknown) | undefined; }> | undefined; px2rem?: { root?: number | undefined; propBlackList?: Array<string> | undefined; propWhiteList?: Array<string> | undefined; selectorBlackList?: Array<string> | undefined; selectorWhiteList?: Array<string> | undefined; selectorDoubleList?: Array<string> | undefined; } | undefined; experimental?: { webpackSyntaxValidate?: Array<string> | undefined; } | undefined; flexBugs?: boolean | undefined; moduleIdStrategy?: string | undefined; optimization?: { skipModules?: boolean | undefined; } | undefined; }
- Default:
{}
Use mako for compilation to significantly improve build speed.
Enable this capability through configuration, which will be passed to mako. Only some common configurations are provided here; more configurations can be set in the mako.config.json
file. For more information, see the mako-config documentation.
manifest
- Type:
{ fileName: string; basePath: string }
- Default:
null
Enable generating an additional manifest file during build to describe the artifacts.
About the parameters: fileName
is the name of the generated file, default is asset-manifest.json
; basePath
adds a prefix to all file paths.
Note: Only generated during build.
mdx
- Type:
{ loader: string; loaderOptions: Object }
- Default:
{}
Configure mdx loader path and loaderOptions parameters.
metas
- Type:
Meta[]
- Default:
[]
Configure additional meta tags.
For example:
metas: [{ name: 'keywords', content: 'umi, umijs' },{ name: 'description', content: 'React framework.' },],
Will generate the following HTML:
<meta name="keywords" content="umi, umijs" /><meta name="description" content="React framework." />
mfsu
- Type:
{ esbuild: boolean; mfName: string; cacheDirectory: string; strategy: 'normal' | 'eager'; include?: string[]; chainWebpack: (memo, args) => void; exclude?: Array<string | RegExp> }
- Default:
{ mfName: 'mf', strategy: 'normal' }
Configure speed-up functionality based on Module Federation.
About the parameters:
esbuild
: When set totrue
, dependency pre-compilation will use esbuild, making first startup faster. The downside is that secondary compilation won't have physical cache and will be slightly slower; recommended for projects with stable dependencies.mfName
: This is the global variable for this solution's remote library, default is mf. Usually configured in micro-frontends to avoid conflicts between main and sub applications.cacheDirectory
: Can customize the cache directory, default isnode_modules/.cache/mfsu
chainWebpack
: Modify dependency webpack configuration using chain programming, based on webpack-chain. See webpack-api documentation for specific APIs.runtimePublicPath
: Will modify the publicPath of mf loading files towindow.publicPath
strategy
: Specifies when mfsu compiles dependencies; innormal
mode, Module Federation remote package is built after babel compilation analysis; ineager
mode, building starts simultaneously with project code using static analysis.include
: Only effective instrategy: 'eager'
mode, used to compensate for dependencies that static analysis cannot detect in eager mode. For example, ifreact
hasn't entered Module Federation remote modules, you can configure{ include: [ 'react' ] }
exclude
: Manually exclude certain dependencies that don't need MFSU processing. Can be strings or regular expressions. For example, if you don't wantvant
to go through MFSU processing, you can configure{ exclude: [ 'vant' ] }
for exact word matching, or{ exclude: [ /vant/ ] }
to exclude any dependencies whoseimport
path matches the regex.
Example:
// Use esbuild for dependency pre-compilationmfsu: {esbuild: true,}// Disable mfsu functionalitymfsu: false;
// webpack configuration modificationmfsu: {
mock
- Type:
{ exclude: string[], include: string[] }
- Default:
{}
Configure mock functionality.
About the parameters. exclude
is used to exclude unwanted mock files; include
is used to add additional mock files outside the mock directory.
Example:
// Make all _mock.ts files under pages become mock filesmock: {include: ['src/pages/**/_mock.ts'],}
Note: This feature is enabled by default. Configure mock: false
to disable it.
mountElementId
- Type:
string
- Default:
'root'
Configure the element id where the React component tree is rendered in HTML.
Example:
mountElementId: 'container'
monorepoRedirect
- Type:
{ srcDir?: string[], exclude?: RegExp[], peerDeps?: boolean, useRootProject?: boolean }
- Default:
false
When using Umi in a monorepo, you might need to import components, utility functions, etc. from other sub-packages. By enabling this option, you can redirect these sub-package imports to their source code location (default is the src
folder). This can also solve the issue of sub-package changes not hot-reloading in MFSU
scenarios.
The benefits of this redirection are: supports hot updates, no need to pre-build other sub-packages for development.
Use srcDir
to adjust the priority location for identifying source code folders, and use exclude
to set dependencies that don't need redirection.
Example:
// Default redirect to sub-package's src foldermonorepoRedirect: {}// In sub-packages, prioritize redirecting to libs foldermonorepoRedirect: {srcDir: ['libs', 'src'],}// Don't redirect @scope/* sub-packagesmonorepoRedirect: {exclude: [/^@scope\/.+/],}
In actual large business monorepos, each sub-package's dependencies are loaded by looking up node_modules
from their directory upward. However, during local development, dependencies are installed in devDependencies
, which behaves differently from npm installation, inevitably leading to multiple instance issues.
INFO
For example, each sub-package needs antd
during local development, installed in devDependencies
and specified in peerDependencies
. We expect that when the package is published to npm and installed by a project, antd
uses the project's own dependency, globally unique. However, in the monorepo, dependencies specified in devDependencies
must exist, and when sub-package code looks for dependencies, it starts from that sub-package, causing each sub-package to use its own antd
, resulting in multiple copies of antd
in the output, increased bundle size, broken message queues, etc.
To solve this issue, we stipulate:
When the peerDeps
option is enabled, all peerDependencies
specified by sub-packages will automatically be added alias
redirection for uniqueness, avoiding multiple instances:
monorepoRedirect: { peerDeps: true }
After redirection, dependencies become globally unique, maintaining consistency with the experience after installing packages from npm.
useRootProject: When your project is not in a monorepo subfolder but at the monorepo root, you can enable this option to make monorepoRedirect effective.
mpa
- Type:
object
- Default:
false
Enable mpa mode.
outputPath
- Type:
string
- Default:
dist
Configure the output path.
Note: Not allowed to be set to directories related to conventional functionality such as src, public, pages, mock, config, locales, models, etc.
phantomDependency
- Type:
{ exclude: string[] }
- Default:
false
Execute phantom dependency detection.
When using dependencies not declared in package.json, and not configured through alias or externals, it will throw an error and remind you.
If you need to whitelist certain dependencies, you can do so through the exclude configuration option. The exclude items are npm dependency package names.
export default {phantomDependency: {exclude: ['lodash']}}
plugins
- Type:
string[]
- Default:
[]
Configure additional Umi plugins.
Array items are paths pointing to plugins, which can be npm dependencies, relative paths, or absolute paths. If it's a relative path, it will start looking from the project root directory.
Example:
plugins: [// npm dependency'umi-plugin-hello',// relative path'./plugin',// absolute path`${__dirname}/plugin.js`,],
polyfill
- Type:
{ imports: string[] }
- Default:
{}
Configure polyfills to be imported on demand. By default, all polyfills are imported.
For example, to only import the stable part of core-js:
polyfill: {imports: ['core-js/stable'],}
If you have more extreme performance requirements, you can consider importing on demand:
polyfill: {imports: ['core-js/features/promise/try', 'core-js/proposals/math-extensions'],}
Note: This feature is enabled by default. Configure polyfill: false
or set environment variable BABEL_POLYFILL=none
to disable it.
postcssLoader
- Type:
object
- Default:
{}
Configure postcss-loader options.
presets
- Type:
string[]
- Default:
[]
Configure additional Umi preset collections.
Array items are paths pointing to preset collections, which can be npm dependencies, relative paths, or absolute paths. If it's a relative path, it will start looking from the project root directory.
Example:
presets: [// npm dependency'umi-preset-hello',// relative path'./preset',// absolute path`${__dirname}/preset.js`,],
proxy
- Type:
object
- Default:
{}
Configure proxy functionality.
For example:
proxy: {'/api': {'target': 'http://jsonplaceholder.typicode.com/','changeOrigin': true,'pathRewrite': { '^/api' : '' },}}
Then accessing /api/users
will access the data from http://jsonplaceholder.typicode.com/users.
Note: The proxy functionality is only effective during development.
publicPath
- Type:
string
- Default:
/
Configure webpack's publicPath.
reactRouter5Compat
- Type:
object
- Default:
false
Enable react-router 5 compatibility mode. In this mode, route component props will include location, match, history, and params properties, maintaining consistency with react-router 5.
However, note that:
- This mode will have additional re-renders
- Due to the history library update, the location still doesn't have a query property
routes
- Type:
Route[]
- Default:
[]
Configure routes. For more information, please see Configuring Routes
routeLoader
- Type:
{ moduleType: 'esm' | 'cjs' }
- Default:
{ moduleType: 'esm' }
Configure how routes are loaded. Setting moduleType to 'cjs' will load route components using require
.
// moduleType: esm'index': React.lazy(() => import(/* webpackChunkName: "p__index" */'../../pages/index.tsx')),// moduleType: cjs'index': React.lazy(() => Promise.resolve(require('../../pages/index.tsx'))),
routePrefetch
- Type:
boolean
- Default:
false
Enable route preloading functionality.
run
- Type:
{ globals: string[] }
- Default:
null
Global injection configuration for the run command. Adding ['zx/globals']
means when using umi run ./script.ts
, umi will automatically inject import 'zx/globals';
, eliminating the need to write import 'zx/globals';
in every script.
runtimePublicPath
- Type:
object
- Default:
null
Enable runtime publicPath, which will use window.publicPath
as the starting path for dynamic resource loading when enabled.
For example:
runtimePublicPath: {},
sassLoader
- Type:
object
- Default:
{}
Configure sass-loader, see sass-loader > options
styleLoader
- Type:
object
- Default:
false
Enable style loader functionality, allowing CSS to be inlined in JS without outputting additional CSS files.
stylusLoader
- Type:
object
- Default:
{}
Configure stylus-loader, see stylus-loader > options
styles
- Type:
string[]
- Default:
[]
Configure additional CSS.
Configuration items support inline styles and external style paths, the latter determined by whether it starts with https?://.
Inserted styles are prepended, with lower priority than user-written styles in the project.
For example:
styles: [`body { color: red; }`, `https://a.com/b.css`],
Will generate the following HTML:
<style>body {color: red;}</style><link rel="stylesheet" href="https://a.com/b.css" />
srcTranspiler
- Type:
string
optional values:babel
,swc
,esbuild
- Default:
babel
Configure the tool for transpiling js/ts during build.
srcTranspilerOptions
- Type:
{ swc?: SwcConfig, esbuild?: EsbuildConfig }
- Default:
undefined
If you use swc
/ esbuild
as the srcTranspiler
transpiler, you can further configure the transpiler through this option. See SwcConfig and EsbuildConfig documentation for details.
For example, adding other plugins to swc:
srcTranspilerOptions: {swc: {jsc: {experimental: {plugins: [['@swc/plugin-styled-components',{displayName: true,ssr: true,},],],},},},}
svgr
- Type:
object
- Default:
{}
svgr is enabled by default, supporting the following way to use React svg components:
import SmileUrl, { ReactComponent as SvgSmile } from './smile.svg';
You can configure svgr's behavior, see @svgr/core > Config for configuration options.
svgo
- Type:
object
- Default:
{}
Uses svgo by default to optimize svg resources, see svgo for configuration options.
targets
- Type:
object
- Default:
{ chrome: 80 }
Configure the minimum browser versions to support. Umi will automatically introduce polyfills, configure autoprefixer, and perform syntax transformations based on this.
Example:
// Support ie11targets: {ie: 11,}
theme
- Type:
object
- Default:
{}
Configure less variable theme.
Example:
theme: { '@primary-color': '#1DA57A' }
title
- Type:
string
- Default:
null
Configure global page title, currently only supports static Title.
verifyCommit
- Type:
{ scope: string[]; allowEmoji: boolean }
- Default:
{ scope: ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'workflow', 'build', 'ci', 'chore', 'types', 'wip', 'release', 'dep', 'deps', 'example', 'examples', 'merge', 'revert'] }
Configuration options for the verify-commit command.
About parameters. scope
is used to configure allowed scopes, case-insensitive, configuration will override the defaults; allowEmoji
when enabled will allow EMOJI prefixes, like 💥 feat(module): added a great feature
.
verifyCommit: {scope: ['feat', 'fix'],allowEmoji: true,}
Note: Commit messages generated by git revert
or git merge
commands and changesets' release merge format will pass verification by default.
vite
- Type:
object
- Default:
{}
Developer's configuration will be merged into vite's default configuration.
Example:
// Change temporary file path to node_modules/.bin/.vite foldervite: {cacheDir: 'node_modules/.bin/.vite',}
writeToDisk
- Type:
boolean
- Default:
false
When enabled, it will output an additional copy of files to the dist directory in dev mode, typically used for chrome extension, electron application, sketch plugin, and other development scenarios.