- 文档渲染配置
- Demo 配置
- Markdown 配置
Open-source MIT Licensed | Copyright © 2019-present
Powered by self
Powered by self
dumi 2 基于 Umi 4,除了自身特有的配置项以外,同样也支持 Umi 4 提供的基础配置项,两者均在 .dumirc.ts
中配置。
// .dumirc.tsimport { defineConfig } from 'dumi';export default defineConfig({...});
用于配置 Markdown 解析相关的行为,包含如下子项。
string[]
['docs']
配置 Markdown 文档的解析目录,路径下的 Markdown 文档会根据目录结构解析为路由。
{ type: string; subType?: string; dir: string }[]
[{ type: 'component', dir: 'src' }]
配置原子资产(例如组件、函数、工具等)Markdown 的解析目录。
其中 type
用于指定资产类别,必须是 URL 友好的单数单词,比如 component
或者 hook
;subType
用于指定资产的子类别,通常在需要生成二级导航时使用,值必须为 URL 友好的单词;dir
指定目录下第一层级的 Markdown 文档会被解析为该实体分类下的路由,嵌套层级将不会识别。比如在默认配置下,src/Foo/index.md
将被解析为 components/foo
的路由,type
配置值将自动被复数化后作为路由的前缀路径。
单独将资产的解析逻辑拆分是为了解决 dumi 1 中普通文档与源码目录下的组件文档混淆不清、分组困难的问题。
'active' | 'passive'
'active'
配置代码块的解析模式。dumi 默认会编译有关联技术栈的代码块(比如内置的 React 技术栈会编译 jsx、tsx 代码块)、将其处理为组件,不需要编译的代码块需要添加 | pure
修饰符才能跳过编译;倘若你希望将这个行为反过来,可以将其配置为 passive
。
两者在使用上的区别如下:
active 模式:```jsxexport default () => '我会被编译,展示为组件';``````jsx | pureexport default () => '我不会被编译,仍然展示为源代码';```passive 模式:```jsxexport default () => '我不会被编译,仍然展示为源代码';``````jsx | demoexport default () => '我会被编译,展示为组件';```
string
undefined
指定项目的入口文件,比如 ./src/index.ts
,目前该配置会用于 API 解析,可参考指南 - 自动 API 表格。
boolean
true
配置强制 kebab-case 路由模式,即所有路径都会被转换为短横线模式,比如 HelloWorld
将会被转换为 hello-world
,该配置默认开启,配置为 false
时将以实际文件路径为准。
{ unpkgHost?: 'https://unpkg.com'; resolveFilter?: (args: { id: string; ids: string; type: 'COMPONENT' | 'FUNCTION' }) => boolean }
undefined
启用 API 自动解析功能,开启后可使用 API
全局组件,参考指南 - 自动 API 表格。
其中 unpkgHost
配置项用于自定义 unpkg.com 的地址以加快访问速度,比如自己的私有镜像地址。解析过程中如果存在找不到的依赖,会兜底到 unpkgHost
的地址去找。
resolveFilter
配置项用于跳过指定原子资产的解析以提升性能。部分组件属性或函数签名存在多层嵌套,甚至是循环引用时,会导致解析结果巨大,此时可以通过该配置项跳过解析。
上述配置是默认 React 解析器的配置, dumi 也提供方法覆盖原有解析器,具体可查看API Table 支持。
boolean
true
是否自动 alias 项目包名到 src 目录,如果是 father 4 项目,还会根据配置自动 alias 产物目录到源码目录,默认开启。
{ id: string, name: string, base?: string }[]
[{ id: 'zh-CN', name: '中文' }]
配置站点的多语言,各子项释义如下:
id
值会作为 dumi 识别 Markdown 文件后缀的依据,以及主题国际化文案的 key
。例如,值为 zh-CN
时意味着 index.zh-CN.md
的文件会被归类到该语言下index.zh-CN.md
与 index.md
等价name
值会作为页面渲染语言切换链接的文本值,当只有一种语言时,不会展示切换链接locales[0]
)为站点默认语言,其余为其他语言,对应页面需带上 base
才能访问到base
值指定该语言的基础路由,对默认语言来说默认值为 /
,对非默认语言来说默认值为 /${id}
,仅在希望 id
和 base
不一致时才需要配置,且仅默认语言支持配置为 /
(string | function | [string, object] | [function, object])[]
[]
配置额外的 remark 插件,用于处理 Markdown 语法树的编译。数组项的值可以是:
(string | function | [string, object] | [function, object])[]
[]
配置额外的 rehype 插件,用于处理 HTML 语法树的编译。数组项的值可以是:
{ ga_v2?: string; baidu?: string; ga?: string }
undefined
dumi 内置了站点统计的功能,目前支持 Google Analytics 和百度统计。
示例:
{analytics: {// google analytics 的 key (GA 4)ga_v2: 'G-abcdefg',// 若你在使用 GA v1 旧版本,请使用 `ga` 来配置ga: 'ga_old_key'// 百度统计的 keybaidu: 'baidu_tongji_key',}}
{ hostname: string, exclude?: string[] }
undefined
启用 sitemap.xml
自动生成功能。hostname
配置项用来指定 URL 的域名前缀,exclude
配置项用来忽略某些不需要包含在 sitemap 中的路由。
{ scriptUrl?: string }
undefined
启用 HTML 转 Sketch 的功能,scriptUrl
配置项用于指定 html2sketch 的脚本地址,如果你不希望使用内置的 CDN 地址,可以选择自定义。
该功能会在 demo 预览器操作栏添加『拷贝到 Sketch』按钮,点击后会将当前 demo 转换为 Sketch 对象并复制到剪贴板,该功能基于 Ant Design - html2sketch 项目,需要注意的是,目前必须配合 Kitchen 插件才能实现在 Sketch 中粘贴,步骤演示如下:
光看演示不过瘾?不妨试试看:
通过 themeConfig
可配置传递给主题的配置项:
// .dumirc.tsimport { defineConfig } from 'dumi';export default defineConfig({themeConfig: {// 主题配置项均放置在这一层},});
具体可用的配置项取决于项目当前使用的主题包,dumi 的默认主题目前支持如下配置项:
boolean | string
true
配置是否在 Markdown 页面内容区域底部展示当前文档的编辑链接。
当配置为 true
时 dumi 会根据项目 package.json
中的 repository
配置及当前分支,使用 hosted-git-info 自动生成编辑链接,仅支持部分代码托管平台;如果你使用的是其他代码托管平台或私有化部署的平台,可以使用字符串模板自定义编辑链接,例如 https://gitlab.example.com/group/repo/{filename}
,其中 {filename}
会被替换为当前文档在仓库中的文件路径。
boolean | string
true
主要用于 API Table 中类型的外链,目的是让没有文档的类型,直接导航到仓库中,方便用户参考。
用法与 editLink
类似,不过其自定义字符串模板比 editLink
多了一个 {line}
:https://gitlab.example.com/group/repo/{filename}?L={line}
boolean
true
配置是否在 Markdown 页面内容区域底部展示当前文档的最后更新时间。
文档最后更新时间来源于 Git 提交记录,如果 Markdown 文档还未被 Git 追踪,那么则会展示构建时间;如果你的文档通过 GitHub Action 进行部署,还需要在 actions/checkout 步骤中加上 fetch-depth: 0
参数以检出所有 Git 提交记录,确保可以 dumi 可以拿到正确的最后更新时间,具体可参考 FAQ - 自动部署。
string | false
dumi 的 LOGO
配置导航栏上的站点 LOGO,如果需要配置为本地图片文件,可将图片资源放入 public
文件夹,例如放置 public/logo.png
,则配置 /logo.png
即可。
配置为 false
时不展示 LOGO。
string
undefined
配置导航栏上的站点名称,不配置时不展示。
Navs
类型:{ title: '导航标题', link: '导航路由', activePath: '高亮路径' }[] | Record<string, { title: '导航标题', link: '导航路由', activePath: '高亮路径' }[]>
Navs | {mode: "override" | "append" | "prepend", value: Navs}
约定式导航
配置导航栏上的导航项,不配置时默认为约定式导航。约定式导航生成规则可参考 约定式路由。
{// 单语言时配置数组即可nav: [{ title: 'Blog', link: '/blog' }],// 多语言时配置对象,key 为语言名nav: {'zh-CN': [{ title: '博客', link: '/blog' }],'en-US': [{ title: 'Blog', link: '/en/blog' }],},// 支持通过 nav 将路由追加到约定路由前面或后面nav: {// mode可选值有:override、append、prepend// - override: 直接覆盖约定导航,与 nav: [{ title: 'Blog', link: '/blog' }] 配置相同// - append: 将 value 中的导航追加到约定路由后面// - prepend: 将 value 中的导航添加到约定路由前面mode: "append",value: [{ title: 'Blog', link: '/blog' }]}}
Record<'/nav_path', { title: '分组名称(可选)', children: { title: '菜单项', link: '菜单路由' }[] }[]>
约定式侧边菜单
配置侧边栏菜单,key
为导航路由,配置后对该导航下的所有一级子页面生效,例如 { '/guide': [] }
只对 /guide
及 /guide/xxx
生效。
不配置时默认为约定式侧边菜单,约定式侧边菜单生成规则可参考 约定式路由。
string | false
Powered by dumi
配置页脚内容,可以是 HTML,配置 false
时不展示。
boolean
false
是否开启 RTL 切换,配置为 true
时导航栏会展示 RTL 按钮,用于将站点文本阅读方向切换为『从右到左』,通常在站点用户群体中有使用希伯来语或阿拉伯语时启用。
boolean
false
是否在代码块中展示行号,配置为 true
时会展示代码行号。
boolean
true
切换页面时是否在页面顶部展示进度条,效果如 nprogress。
{ default: 'light' | 'dark' | 'auto'; switch: boolean }
{ default: 'light', switch: true }
配置站点的主题色,其中 default
配置项为默认主题色,默认为亮色模式,配置为 auto
时将跟随用户的操作系统配置自动切换;switch
配置项控制主题色切换器的展示与否,配置为 false
时用户将无法主动切换站点主题色。
对于普通文档站点来说,建议保持 switch
的默认值 true
,将站点主题色的选择权交给用户,同时可以考虑将 default
设置为 auto
以跟随用户的系统配置:
export default {themeConfig: {prefersColor: { default: 'auto' },},};
对于组件库文档站点来说,建议根据组件库对暗色模式的适配情况来选择是否配置 switch
为 false
,避免用户切换主题色后组件 demo 的样式出现异常。
请勿在组件源码或组件 demo 内使用 dumi 提供的 API 强行适配暗色模式,这将导致组件发布后工作异常,因为 dumi 的 API 仅在 dumi 的框架中可用!
正确做法是和 antd 一样提供类似 ConfigProvider
的全局配置组件来控制组件的主题色,再使用 usePrefersColor
API 在 GlobalLayout
中实现站点主题色和组件主题色的切换联动,具体可参考 usePrefersColor
API 的 使用示例。
对于主题开发者来说,可以在 Less 文件中使用 @dark-selector
的全局变量来为主题包的组件增加暗色模式的样式:
.some-container {// 亮色模式为白色color: #fff;// 暗色模式变黑色@{dark-selector} & {color: #000;}}
如果想要在顶部导航栏右侧增加一些社交网站的外链图标,可以通过 socialLinks
进行配置,目前最多支持配置 5 个外链图标
目前支持以下社交平台图标:
Key | 描述 |
---|---|
github | GitHub 平台 |
微博平台 | |
x | X(Twitter)平台 |
gitlab | Gitlab 平台 |
Facebook 平台 | |
zhihu | 知乎平台 |
yuque | 语雀平台 |
Linkedin 平台 |
export default {themeConfig: {socialLinks: {github: 'https://github.com/umijs/dumi',weibo: 'https://xxxx',twitter: 'https://xxxx',gitlab: 'https://xxxx',facebook: 'https://xxxx',zhihu: 'https://xxxx',yuque: 'https://xxxx',linkedin: 'https://xxxx',},},};
对于 dumi 中能使用的自定义配置,你可以使用项目根目录的 .dumirc.ts
文件或者 config/config.ts
,值得注意的是这两个文件功能一致,仅仅是存在目录不同,2 选 1 ,.dumirc.ts
文件优先级较高。
更多目录相关信息介绍,你可以在目录结构了解。
dumi 的配置文件是一个正常的 node 模块,它在执行 dumi 命令行的时候使用,并且不包含在浏览器端构建中。
这里有一个最简单的 dumi 配置文件的范例:
import { defineConfig } from 'dumi';export default defineConfig({outputPath: 'dist',});
使用 defineConfig
包裹配置是为了在书写配置文件的时候,能得到更好的拼写联想支持。如果你不需要,直接 export default {}
也可以。
值得关注的是在你使用 dumi 的时候,你不需要了解每一个配置的作用。你可以大致的浏览一下以下 dumi 支持的所有配置,然后在你需要的时候,再回来查看如何启用和修改你需要的内容。
为方便查找,以下配置项通过字母排序。
Record<string, string>
{}
配置别名,对 import 语句的 source 做映射。
比如:
{alias: {foo: '/tmp/to/foo',}}
然后代码里 import 'foo'
实际上会 import '/tmp/to/foo'
。
有几个 Tip。
1、alias 的值最好用绝对路径,尤其是指向依赖时,记得加 require.resolve
,比如,
// ⛔{alias: {foo: 'foo',}}// ✅{alias: {foo: require.resolve('foo'),}}
2、如果不需要子路径也被映射,记得加 $
后缀,比如
// import 'foo/bar' 会被映射到 import '/tmp/to/foo/bar'{alias: {foo: '/tmp/to/foo',}}// import 'foo/bar' 还是 import 'foo/bar',不会被修改{alias: {foo$: '/tmp/to/foo',}}
object
{ flexbox: 'no-2009' }
用于解析 CSS 并使用来自 Can I Use 的值将供应商前缀添加到 CSS 规则。如自动给 CSS 添加 -webkit-
前缀。
更多配置,请查阅 autoprefixer 的配置项。
object
{}
通过指定 ANALYZE=1
环境变量分析产物构成时,analyzer 插件的具体配置项,见 webpack-bundle-analyzer
string
/
要在非根目录下部署 dumi 项目时,你可以使用 base 配置。
base 配置允许你为应用程序设置路由前缀。比如有路由 /
和 /users
,设置 base 为 /foo/
后就可通过 /foo/
和 /foo/users
访问到之前的路由。
注意:base 配置必须在构建时设置,并且不能在不重新构建的情况下更改,因为该值内联在客户端包中。
string
node_modules/.cache
默认情况下 dumi 会将构建中的一些缓存文件存放在 node_modules/.cache
目录下,比如 logger 日志,webpack 缓存,mfsu 缓存等。你可以通过使用 cacheDirectoryPath
配置来修改 dumi 的缓存文件目录。
示例,
// 更改缓存文件路径到 node_modules/.cache1 文件夹cacheDirectoryPath: 'node_modules/.cache1',
(memo, args) => void
null
为了扩展 dumi 内置的 webpack 配置,我们提供了用链式编程的方式修改 webpack 配置,基于 webpack-chain,具体 API 可参考 webpack-api 的文档。
如下所示:
export default {chainWebpack(memo, args) {return memo;},};
该函数具有两个参数:
memo
是现有 webpack 配置args
包含一些额外信息和辅助对象,目前有 env
和 webpack
。env
为当前环境,值为 development
或 production
;webpack
为 webpack 对象,可从中获取 webpack 内置插件等用法示例:
export default {chainWebpack(memo, { env, webpack }) {// 设置 aliasmemo.resolve.alias.set('foo', '/tmp/to/foo');// 添加额外插件memo.plugin('hello').use(Plugin, [...args]);// 删除 dumi 内置插件memo.plugins.delete('hmr');},};
{ editor?: string }
false
当前仅 React 项目支持。
开启后,可通过 Option+Click/Alt+Click
点击组件跳转至编辑器源码位置,Option+Right-click/Alt+Right-click
可以打开上下文,查看父组件。
关于参数。editor
为编辑器名称,默认为 'vscode',支持 vscode
& vscode-insiders
。
配置 clickToComponent 的行为,详见 click-to-component。
示例:
// .dumirc.tsexport default {clickToComponent: {},};
{ jsStrategy: 'bigVendors' | 'depPerChunk' | 'granularChunks'; jsStrategyOptions: {} }
null
用于配置 code splitting 的策略方案,dumi 默认以路由为分界拆分 chunk,实现路由维度的 chunk 按需加载,如果在此之上希望继续提取公共 chunk,可以选择合适的策略进行配置,差异如下。
bigVendors 是大 vendors 方案,会将 async chunk 里的 node_modules 下的文件打包到一起,可以避免重复。同时缺点是,1)单文件的尺寸过大,2)毫无缓存效率可言。
depPerChunk 和 bigVendors 类似,不同的是把依赖按 package name + version 进行拆分,算是解了 bigVendors 的尺寸和缓存效率问题。但同时带来的潜在问题是,可能导致请求较多。我的理解是,对于非大型项目来说其实还好,因为,1)单个页面的请求不会包含非常多的依赖,2)基于 HTTP/2,几十个请求不算问题。但是,对于大型项目或巨型项目来说,需要考虑更合适的方案。
granularChunks 在 bigVendors 和 depPerChunk 之间取了中间值,同时又能在缓存效率上有更好的利用。无特殊场景,建议用 granularChunks 策略。
boolean
undefined
src/layouts/index.[tsx|vue|jsx|js]
为约定式布局,默认开启。可通过配置 conventionLayout: false
关闭该默认行为。
{ base: string; exclude: RegExp[] }
{ base: './.dumi/pages', exclude: [/(\/|^)(\.|_\/)/] }
修改默认的约定式路由规则,仅在使用 dumi 约定式路由时有效,约定式路由也叫文件路由,就是不需要手写配置,文件系统即路由,通过目录和文件及其命名分析出路由配置。
使用约定式路由时,约定 .dumi/pages
下所有的 (j|t)sx?
文件即路由。
你可以从约定式路由查看更多说明。
base
用于设置约定的路由的基础路径,默认从 .dumi/pages
读取,如果是文档站点可能会需要将其改成 ./docs
;
你可以使用 exclude
配置过滤一些不需要的文件,比如用于过滤 components、models 等。
示例,
// 不识别 components 和 models 目录下的文件为路由conventionRoutes: {exclude: [/\/components\//, /\/models\//],}
Array<string | { from: string; to: string; }>
[]
配置要复制到输出目录的文件或文件夹。
当配置字符串时,默认拷贝到产物目录,如:
copy: ['foo.json', 'src/bar.json']
会产生如下产物的结构:
+ dist- bar.json- foo.json+ src- bar.json- foo.json
你也可以通过对象配置具体的拷贝位置,其中相对路径的起点为项目根目录:
copy: [{ from: 'from', to: 'dist/output' },{ from: 'file.json', to: 'dist' }]
此时将产生如下产物结构:
+ dist+ output- foo.json- file.json+ from- foo.json- file.json
{ includes?: string[] }
false
配置 script 标签的 crossorigin。如果有声明,会为本地 script 加上 crossorigin="anonymous" 的属性。
关于参数。includes
参数可以为额外的非本地 script 标签加上此属性。
比如:
crossorigin: {}
然后输出的 HTML 中会有这些变化,
-<script src="/umi.js"></script>+<script src="/umi.js" crossorigin="anonymous"></script>
string
可选的值:esbuild
, cssnano
, parcelCSS
, none
esbuild
配置构建时使用的 CSS 压缩工具; none
表示不压缩。
示例:
{cssMinifier: 'esbuild'}
object
{}
cssMinifier
CSS 压缩工具配置选项。
示例:
{cssMinifier: 'esbuild',cssMinifierOptions: {minifyWhitespace: true,minifySyntax: true,},}
对应 CSS 压缩的配置请查看对应的文档。
string
./
为 CSS 中的图片、文件等外部资源指定自定义公共路径。作用类似于 publicPath
默认值是 ./
。
object
{}
配置 css-loader ,详见 css-loader > options
Record<string, string>
{'process.env.NODE_ENV' : process.env.NODE_ENV,'process.env.HMR' : process.env.HMR,'process.env.SOCKET_SERVER': process.env.ERROR_OVERLAY'}
基于define-plugin 插件设置代码中的可用变量。
JSON.stringify
转换。{'a.b.c': 'abcValue'}
是无法替换代码中的 a.b?.c
的比如,
define: { FOO: 'bar' }
然后代码里的 console.log(hello, FOO)
会被编译成 console.log(hello, 'bar')
。
当你在 ts 的项目中使用这些变量时,你需要在 typings 文件中声明变量类型,以支持 ts 类型提示,比如:
如果你的 typings 文件是全局的:
// typings.d.tsdeclare const FOO: string;
如果你的 typings 文件是非全局的(包含了 import/export):
// typings.d.tsimport './other.d.ts';declare global {const FOO: string;}
string
cheap-module-source-map
,build 时候默认无 sourcemap设置 sourcemap 生成方式。
常见可选值有:
eval
,最快的类型,缺点是不支持低版本浏览器source-map
,最慢但最全的类型示例,
// 关闭 dev 阶段的 sourcemap 生成devtool: false;// 只设置 dev 阶段的 sourcemapdevtool: process.env.NODE_ENV === 'development' ? 'eval' : false;
object
{}
设置 babel class-properties 启用 loose
boolean
true
修复 esbuild 压缩器自动引入的全局变量导致的命名冲突问题。
由于 dumi 默认使用 esbuild 作为压缩器,该压缩器会自动注入全局变量作为 polyfill ,这可能会引发 异步块全局变量冲突、 qiankun 子应用和主应用全局变量冲突 等问题,通过打开该选项或切换 jsMinifier
压缩器可解决此问题。
更多信息详见 vite#7948 。
示例,
esbuildMinifyIIFE: true
Record<string, string> | Function
{}
设置哪些模块不打包,转而通过 <script>
或其他方式引入,通常需要搭配 headScripts 配置使用。
示例,
// external reactexternals: { react: 'React' },headScripts: ['https://unpkg.com/react@17.0.1/umd/react.production.min.js'],
注意:不要轻易设置 antd 的 externals,由于依赖较多,使用方式复杂,可能会遇到较多问题,并且一两句话很难解释清楚。
Array<string | RegExp>
[]
配置额外需要做 Babel 编译的 NPM 包或目录。比如:
export default {extraBabelIncludes: [// 支持绝对路径join(__dirname, '../../common'),// 支持 npm 包'react-monaco-editor',// 转译全部路径含有 @scope 的包/@scope/],};
string[] | Function
[]
配置额外的 babel 插件。可传入插件地址或插件函数。
string[] | Function
[]
配置额外的 babel 插件集。可传入插件集地址或插件集函数。
PostCSSPlugin[]
[]
配置额外的 postcss 插件。
{ extraRoutePaths: IUserExtraRoute[] | (() => IUserExtraRoute[] | Promise<IUserExtraRoute[]>), ignorePreRenderError: boolean }
{}
开启该配置后会针对每个路由单独输出 HTML 文件,通常用于静态站点托管。例如项目有如下路由:
//docs/docs/a
不开启 exportStatic
时会输出:
dist/index.html
开启 exportStatic
时会输出:
dist/index.htmldist/docs/index.htmldist/docs/a/index.html
通过 extraRoutePaths
子配置项可以产出额外的页面,通常用于动态路由静态化。例如有如下路由:
/news/:id
默认情况下只会输出 dist/news/:id/index.html
,但可以通过配置 extraRoutePaths
将其静态化:
// .dumirc.tsexport default {exportStatic: {// 配置固定值extraRoutePaths: ['/news/1', '/news/2'],// 也可以配置函数动态获取extraRoutePaths: async () => {const res = await fetch('https://api.example.com/news');const data = await res.json();return data.map((item) => `/news/${item.id}`);},},}
此时输出文件会变成:
dist/news/:id/index.htmldist/news/1/index.htmldist/news/2/index.html
extraRoutePaths
除了支持配置字符串数据,还可以配置成对象数组,用于启用 SSR 时又希望对部分路由禁用预渲染的场景,例如:
// .dumirc.tsexport default {exportStatic: {// 输出额外页面文件但跳过预渲染extraRoutePaths: [{ path: '/news/1', prerender: false }],},}
exportStatic
在搭配 ssr
使用时会进行预渲染,在预渲染失败时会抛出异常并终止构建,可以通过配置 ignorePreRenderError
来忽略预渲染失败的错误,例如:
// .dumirc.tsexport default {exportStatic: {// 忽略预渲染失败的错误ignorePreRenderError: true,},}
string[]
null
默认情况下,站点将使用约定 favicon
来创建图标的 meta 头标签。
通过如下方式自定义:
favicons: [// 完整地址'https://domain.com/favicon.ico',// 此时将指向 `/favicon.png` ,确保你的项目含有 `public/favicon.png`'/favicon.png']
{ ReactCompilerConfig: object }
null
是否开启 React Compiler(React Forget)功能。参考 https://react.dev/learn/react-compiler 。
forget: {ReactCompilerConfig: {},},
注意:
1、forget 和 mfsu、mako 暂时不兼容,如果开启了 forget,同时 mfsu、mako 有打开时会抛错。 2、forget 需要 react 19,使用时,请手动安装 react@rc 和 react-dom@rc 到项目依赖。
object
null
开启 TypeScript 的类型检查。基于 fork-ts-checker-webpack-plugin,配置项可参考 fork-ts-checker-webpack-plugin 的 Options。
boolean
true
开启 hash 模式,让 build 之后的产物包含 hash 后缀。通常用于增量发布和避免浏览器加载缓存。
启用后,产物通常是这样,
+ dist- logo.sw892d.png- umi.df723s.js- umi.8sd8fw.css- index.html
注意:HTML 文件始终没有 hash 后缀。
string[] | Script[]
[]
配置 <head>
中的额外 script。
比如,
headScripts: [`alert(1);`, `https://a.com/b.js`],
会生成 HTML,
<script>alert(1);</script><script src="https://a.com/b.js"></script>
如果需要额外属性,切换到对象格式,比如,
headScripts: [{ src: '/foo.js', defer: true },{ content: `alert('你好');`, charset: 'utf-8' },],
{ type: 'browser' | 'hash' | 'memory' }
{ type: 'browser' }
设置路由 history 类型。
{}
false
让 history 带上 query。除了通过 useNavigate
进行的跳转场景,此时还需自行处理 query。
{ cert: string; key: string; hosts: string[]; http2?: boolean }
{ hosts: ['127.0.0.1', 'localhost'] }
开启 dev 的 https 模式,dumi 默认使用 mkcert
快捷创建证书,请确保已经安装。
关于参数。
cert
和 key
分别用于指定 cert 和 key 文件。hosts
用于指定要支持 https 访问的 host,默认是 ['127.0.0.1', 'localhost']
。http2
用于指定是否使用 HTTP 2.0 协议,默认是 true(使用 HTTP 2.0 在 Chrome 或 Edge 浏览器中中有偶然出现 ERR_HTTP2_PROTOCOL_ERRO
报错,如有遇到,建议配置为 false)。示例,
https: {}
boolean
true
忽略 moment 的 locale 文件,用于减少产物尺寸。
注意:此功能默认开。配置 ignoreMomentLocale: false
关闭。
number
10000
(10k)配置图片文件是否走 base64 编译的阈值。默认是 10000 字节,少于他会被编译为 base64 编码,否则会生成单独的文件。
string
,可选值 esbuild
, terser
, swc
, uglifyJs
, none
esbuild
配置构建时压缩 JavaScript 的工具;none
表示不压缩。
示例:
{jsMinifier: 'esbuild'}
object
{}
jsMinifier
的配置项;默认情况下压缩代码会移除代码中的注释,可以通过对应的 jsMinifier
选项来保留注释。
示例:
{jsMinifier: 'esbuild',jsMinifierOptions: {minifyWhitespace: true,minifyIdentifiers: true,minifySyntax: true,}}
配置项需要和所使用的工具对应,具体参考对应文档:
object
{ modifyVars: userConfig.theme, javascriptEnabled: true }
设置 less-loader 的 Options。具体参考参考 less-loader 的 Options。
默认是用 less@4 版本,如果需要兼容 less@3 请配置使用less-options-math。
{ buildOnly?: boolean; nodeModulesTransform?: boolean; checkOutput?: boolean; }
false
当你需要兼容低版本浏览器时,可能需要该选项,开启后将默认使用 非现代 的打包工具做构建,这会显著增加你的构建时间。
legacy: {}
默认只在构建时生效,通过设定 buildOnly: false
关闭该限制。
可通过打开 checkOutput: true
选项,每次构建结束后将自动运行 es-check
检查产物 .js
文件的语法是否为 es5 格式。
开启此选项后:
srcTranspiler
、jsMinifier
、 cssMinifier
选项。node_modules
内的源码,targets
兼容至 ie 11 ,通过指定 nodeModulesTransform: false
来取消对 node_modules
的转换,此时你可以通过配置 extraBabelIncludes
更精准的转换那些有兼容性问题的包。externals
时,确保你没有在使用异步性质的 externalsType
时又使用了同步导入依赖。Link[]
[]
配置额外的 link 标签。
示例,
links: [{ href: '/foo.css', rel: 'preload' }],
{ 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; }
{}
使用 mako 用于编译以显著提高构建速度。
通过配置以启用这个能力,配置将传递给mako。这里只提供了一些常用的配置,更多的配置可以在 mako.config.json
文件中设置。有关更多信息,请参阅mako-config文档。
{ fileName: string; basePath: string }
null
开启 build 时生成额外的 manifest 文件,用于描述产物。
关于参数。fileName
是生成的文件名,默认是 asset-manifest.json
;basePath
会给所有文件路径加上前缀。
注意:只在 build 时生成。
Meta[]
[]
配置额外的 meta 标签。
比如,
metas: [{ name: 'keywords', content: 'dumi, base on dumi' },{ name: 'description', content: 'React framework.' },],
会生成以下 HTML,
<meta name="keywords" content="dumi, base on dumi" /><meta name="description" content="React framework." />
{ esbuild: boolean; mfName: string; cacheDirectory: string; include?: string[]; chainWebpack: (memo, args) => void; exclude?: Array<string | RegExp> }
{ mfName: 'mf' }
配置基于 Module Federation 的提速功能。
关于参数
esbuild
配为 true
后会让依赖的预编译走 esbuild,从而让首次启动更快,缺点是二次编译不会有物理缓存,稍慢一些;推荐项目依赖比较稳定的项目使用。mfName
是此方案的 remote 库的全局变量,默认是 mf,通常在微前端中为了让主应用和子应用不冲突才会进行配置cacheDirectory
可以自定义缓存目录,默认是 node_modules/.cache/mfsu
chainWebpack
用链式编程的方式修改 依赖的 webpack 配置,基于 webpack-chain,具体 API 可参考 webpack-api 的文档;runtimePublicPath
会让修改 mf 加载文件的 publicPath 为 window.publicPath
exclude
手动排除某些不需要被 MFSU 处理的依赖, 字符串或者正则的形式,比如 vant
不希望走 MFSU 处理,可以配置 { exclude: [ 'vant' ] }
匹配逻辑为全词匹配,也可以配置 { exclude: [ /vant/ ] }
只要 import
路径中匹配该正则的依赖都不走 MFSU 处理示例,
// 用 esbuild 做依赖预编译mfsu: {esbuild: true,}// 关闭 mfsu 功能mfsu: false;
// webpack 配置修改mfsu: {chainWebpack(memo, args) {// 添加额外插件memo.plugin('hello').use(Plugin, [...args]);return memo;}}
注意:此功能默认开。配置 mfsu: false
关闭。
{ exclude: string[], include: string[] }
{}
配置 mock 功能。
关于参数。exclude
用于排除不需要的 mock 文件;include
用于额外添加 mock 目录之外的 mock 文件。
示例,
// 让所有 pages 下的 _mock.ts 文件成为 mock 文件mock: {include: ['.dumi/pages/**/_mock.ts'],}
注意:此功能默认开。配置 mock: false
关闭。
string
'root'
配置 react 组件树渲染到 HTML 中的元素 id。
示例,
mountElementId: 'container'
{ srcDir?: string[], exclude?: RegExp[], peerDeps?: boolean, useRootProject?: boolean }
false
在 monorepo 中使用 dumi 时,你可能需要引入其他子包的组件、工具方法等,通过开启此选项来重定向这些子包的导入到他们的源码位置(默认为 src
文件夹),这也可以解决 MFSU
场景改动子包不热更新的问题。
这种重定向的好处是:支持热更新,无需预构建其他子包即可进行开发。
通过配置 srcDir
来调整识别源码文件夹的优先位置,通过 exclude
来设定不需要重定向的依赖范围。
示例:
// 默认重定向到子包的 src 文件夹monorepoRedirect: {}// 在子包中寻找,优先定向到 libs 文件夹monorepoRedirect: {srcDir: ['libs', 'src'],}// 不重定向 @scope/* 的子包monorepoRedirect: {exclude: [/^@scope\/.+/],}
在实际的大型业务 monorepo 中,每个子包的依赖都是从他们的目录开始向上寻找 node_modules
并加载的,但在本地开发时,依赖都安装在 devDependencies
,和从 npm 上安装表现不一致,所以不可避免会遇到多实例问题。
举个例子,每个子包在本地开发时都需要 antd
,在 devDependencies
中安装了,也在 peerDependencies
中指明了 antd
,我们预期该包发布到 npm ,被某个项目安装后, antd
是使用的项目本身的依赖,全局唯一,但由于在 monorepo 中,指定在 devDependencies
中的依赖必定存在,且子包代码寻找依赖时是从该子包进行的,导致了每个子包都用了自己的 antd
,出现了产物中有多份 antd
、产物体积增大、消息队列被破坏等情况。
为了解决这种问题,我们约定:
当打开 peerDeps
选项时,所有子包指明的 peerDependencies
都会被自动添加 alias
重定向唯一化,避免多实例的存在:
monorepoRedirect: { peerDeps: true }
经过重定向,依赖全局唯一,便可以在开发时保持和在 npm 上安装包后的体验一致。
useRootProject: 当你的项目不在 monorepo 子文件夹里,而在 monorepo 根的话,你可以开启这个选项,以使 monorepoRedirect 生效。
string
dist
配置输出路径。
注意:不允许设定为 src、public、pages、mock、config、locales、models 等约定式功能相关的目录。
string[]
[]
配置额外的 dumi 插件。
数组项为指向插件的路径,可以是 npm 依赖、相对路径或绝对路径。如果是相对路径,则会从项目根目录开始找。
示例,
plugins: [// npm 依赖'dumi-plugin-hello',// 相对路径'./plugin',// 绝对路径`${__dirname}/plugin.js`,],
{ imports: string[] }
{}
设置按需引入的 polyfill。默认全量引入。
比如只引入 core-js 的 stable 部分,
polyfill: {imports: ['core-js/stable'],}
如果对于性能有更极致的要求,可以考虑按需引入,
polyfill: {imports: ['core-js/features/promise/try', 'core-js/proposals/math-extensions'],}
注意:此功能默认开。配置 polyfill: false
或设置环境变量 BABEL_POLYFILL=none
关闭。
object
{}
string[]
[]
配置额外的 dumi 插件集。
数组项为指向插件集的路径,可以是 npm 依赖、相对路径或绝对路径。如果是相对路径,则会从项目根目录开始找。
示例,
presets: [// npm 依赖'dumi-preset-hello',// 相对路径'./preset',// 绝对路径`${__dirname}/preset.js`,],
object
{}
配置代理功能。
比如,
proxy: {'/api': {'target': 'http://jsonplaceholder.typicode.com/','changeOrigin': true,'pathRewrite': { '^/api' : '' },}}
然后访问 /api/users
就能访问到 http://jsonplaceholder.typicode.com/users 的数据。
注意:proxy 功能仅在 dev 时有效。
string
/
配置 webpack 的 publicPath。
Route[]
[]
配置路由。非推荐用法,暂不提供示例
{ moduleType: 'esm' | 'cjs' }
{ moduleType: 'esm' }
配置路由加载方式。moduleType 配置为 'cjs' 会用 require
的方式加载路由组件。
// moduleType: esm'index': React.lazy(() => import(/* webpackChunkName: "p__index" */'../../pages/index.tsx')),// moduleType: cjs'index': React.lazy(() => Promise.resolve(require('../../pages/index.tsx'))),
{ globals: string[] }
null
run 命令的全局注入配置。添加['zx/globals']
,在使用dumi run ./script.ts
的时候,dumi会自动注入import 'zx/globals';
,从而省略掉每个脚本都要写import 'zx/globals';
。
object
null
启用运行时 publicPath,开启后会使用 window.publicPath
作为资源动态加载的起始路径。
比如,
runtimePublicPath: {},
string[] | Script[]
[]
配置 <body>
中额外的 script 标签。
比如,
scripts: [`alert(1);`, `https://a.com/b.js`],
会生成 HTML,
<script>alert(1);</script><script src="https://a.com/b.js"></script>
如果需要额外属性,切换到对象格式,比如,
scripts: [{ src: '/foo.js', defer: true },{ content: `alert('你好');`, charset: 'utf-8' },],
object
{}
配置 sass-loader ,详见 sass-loader > options
object
false
启用 style loader 功能,让 CSS 内联在 JS 中,不输出额外的 CSS 文件。
object
{}
配置 stylus-loader ,详见 stylus-loader > options
string[]
[]
配置额外的 CSS。
配置项支持内联样式和外联样式路径,后者通过是否以 https?:// 开头来判断。
插入的样式会前置,优先级低于项目内用户编写样式。
比如:
styles: [`body { color: red; }`, `https://a.com/b.css`],
会生成以下 HTML,
<style>body {color: red;}</style><link rel="stylesheet" href="https://a.com/b.css" />
string
可选的值:babel
, swc
, esbuild
babel
配置构建时转译 js/ts 的工具。
{ swc?: SwcConfig, esbuild?: EsbuildConfig }
undefined
如果你使用了 swc
/ esbuild
作为 srcTranspiler
转译器,你可以通过此选项对转译器做进一步的配置,详见 SwcConfig 、 EsbuildConfig 配置文档。
如给 swc 添加其他的插件:
srcTranspilerOptions: {swc: {jsc: {experimental: {plugins: [['@swc/plugin-styled-components',{displayName: true,ssr: true,},],],},},},}
object
{}
svgr 默认开启,支持如下方式使用 React svg 组件:
import SmileUrl, { ReactComponent as SvgSmile } from './smile.svg';
可配置 svgr 的行为,配置项详见 @svgr/core > Config。
object
{}
默认使用 svgo 来优化 svg 资源,配置项详见 svgo 。
object
{ chrome: 80 }
配置需要兼容的浏览器最低版本。dumi 会根据这个自定引入 polyfill、配置 autoprefixer 和做语法转换等。
示例,
// 兼容 ie11targets: {ie: 11,}
object
{}
配置 less 变量主题。
示例:
// 修改 dumi 默认主题的主色,更多变量详见:https://github.com/umijs/dumi/blob/master/src/client/theme-default/styles/variables.less(theme: { '@c-primary': '#1DA57A' })
string
null
配置全局页面 title,暂时只支持静态的 Title。
boolean
false
开启后会在 dev 模式下额外输出一份文件到 dist 目录,通常用于 chrome 插件、electron 应用、sketch 插件等开发场景。