- 介绍
- 什么是 dumi
Open-source MIT Licensed | Copyright © 2019-present
Powered by self
Powered by self
参考该文档可将 dumi 1.x 项目升级到 dumi 2.0,如果你的项目是从 dumi 1.x 早期的组件研发脚手架初始化,建议同时将项目中的 father-build 升级到 father 4,以获得更好的组件源码构建体验。
dumi 2.0 最低支持 Node.js v14 版本,升级前请确保设备安装的 Node.js 版本是 14+。
倘若在 dumi 1.x 初始化模板的基础上改动不大,建议使用 create-dumi
重新初始化一套模板,将源码及文档拷贝进去、再做适当调整验证。
确保以下操作是在 git 仓库中进行,且工作区是干净的:
$ git rm -rf ./* # 清空现有仓库文件(仅工作区清空,文件仍受 Git 版本控制)$ npx create-dumi # 然后选择需要的模板$ rm -rf docs src # 删除初始化模板的 docs 及 src$ git checkout src docs # 恢复原有的源码及文档
至此模板升级完成,可进行后续的文档及配置升级。
倘若在 dumi 1.x 初始化模板的基础上改动较大,建议手动升级做最小化调整,步骤如下:
{"scripts": {+ "prepare": "dumi setup"},"devDependencies": {- "dumi": "^1.0.0",+ "dumi": "^2.0.0"}}
{"compilerOptions": {"paths": {+ "@@/*": [".dumi/tmp/*"]}}}
- .umi- .umi-test- .umi-production+ .dumi/tmp+ .dumi/tmp-test+ .dumi/tmp-production
单标签改为双标签。
- <code src="path/to/demo.tsx" />+ <code src="path/to/demo.tsx"></code>
dumi 2.0 将使用特有的 .dumirc.ts
作为配置文件,请将原有的 .umirc.ts
或者 config/config.ts
重命名为 .dumirc.ts
,并做如下调整:
+ import { defineConfig } from 'dumi';- export default {+ export default defineConfig({# 以下为文档配置升级# 已内置全文搜索,默认不再集成 algolia,有需要可以手动覆盖 SearchBar 组件- algolia: { ... },# 由于 doc 模式已废弃,所以该配置项也一并废弃- mode: 'doc',# dumi 1.x 用 title 作为组件库名称,如果你希望设置的是组件库名称而非页面标题,请改用 name- title: 'xxx',+ themeConfig: { name: 'xxx' },# logo 配置项升级- logo: 'xxx',+ themeConfig: { logo: 'xxx' },# menus 升级为 themeConfig.sidebar- menus: [...],+ themeConfig: {+ sidebar: {+ '/guide': {+ title: '分组名称(可选)',+ children: [{ title: '标题', link: '链接' }],+ },+ },+ },# navs 升级为 themeConfig.nav- navs: [...],+ themeConfig: {+ nav: [{ title: '标题', link: '链接' }],+ },# locales 配置格式升级- locales: [['zh-CN', '中文']],+ locales: [{ id: 'zh-CN', name: '中文' }], // 2.0 默认值# resolve 配置项升级resolve: {# 拆分普通文档解析(多层)和资产文档(单层 + 按分类添加路由前缀)解析,可访问约定式路由了解更多- includes: ['docs', 'src'],+ docDirs: ['docs'], // 2.0 默认值+ atomDirs: [{ type: 'component', dir: 'src' }], // 2.0 默认值# passive 配置项升级,用 codeBlockMode 替代- passivePreview: true,+ codeBlockMode: 'passive',# 废弃,由注册的技术栈决定解析什么语言的 demo- previewLangs: [...],},sitemap: {- excludes: [...],# sitemap.excludes 配置项升级+ exclude: [...],},# apiParser 的子配置项暂不支持,后续版本会支持apiParser: {- ...},# 以下为基础配置升级# favicon 配置项升级- favicon: 'xxx',+ favicons: ['xxx'],# 已废弃,默认开启动态加载- dynamicImport: {},# 默认开启- fastRefresh: {},# 默认使用 webpack 5- webpack5: {},});
Monorepo 模式下特别注意 🚨:
由于 dumi 2
不再感知 monorepo
,因此会出现热更新失效的问题,需要手动配置包名到 src 的 alias。
alias: {pkg: path.join(__dirname, 'packages/pkg/src');}
由于 dumi 2.0 拆分了普通文档与资产文档的解析逻辑,其中资产文档的解析仅识别解析路径顶层 md 及顶层下的 index.md,所以在 src
下的文档目录结构可能需要做调整,例如:
.└── src├── Foo│ ├── index.md # ✅ 识别│ └── a.md # ❗️ 非 index.md 不再识别├── components│ └── Bar│ └── index.md # ❗️ 嵌套层级不再识别└── Hello.md # ✅ 识别
如果不方便调整结构,可以通过配置 resolve.atomDirs
来指定识别的目录,例如:
export default {resolve: {atomDirs: [{ type: 'component', dir: 'src' }, // 默认值# 追加一个组件资产的解析目录+ { type: 'component', dir: 'src/components' },]}}
Monorepo 模式下
export default {resolve: {atomDirs: [{ type: 'component', dir: 'src' }, // 默认值# 做顶级路由的区分,被解析到的 md 均有对应 `type` 复数形式的路由前缀,例如 `/basic-components/foo`+ { type: 'basic-component', dir: 'packages/basic/src' },+ { type: 'complex-component', dir: 'packages/complex/src' },]}}
Markdown 头部支持的 frontmatter 有如下变化:
---nav:# 不支持配置路径,以文件夹目录结构为准- path: /xxxxgroup:# 不支持配置路径,group 没有路径的概念了- path: /xxxx# 已废弃- legacy: /xxxxhero:# 新的默认主题不支持展示 hero 图片- image: xxxx# desc 配置项升级- desc: xxxx+ description: xxxxfeatures:# 新的默认主题只支持配置 emoji 作为图标- - icon: xxxx+ - emoji: 🚀# desc 配置项升级- desc: xxxx+ description: xxxx# 请在 .dumirc.ts 的 themeConfig.footer 中配置- footer: xxx# 已废弃- translateHelp: true# hide 配置项升级为 debug- hide: true+ debug: true# 以下配置暂不支持,后续版本会支持- sidemenu: false---
Demo 支持的 frontmatter 有如下变化:
/**# desc 配置项升级-* desc: xxxx+* description: xxxx# 已废弃,可通过覆盖 PreviewerActions 组件实现全局控制-* hideActions: ['xxx']*/
至此,可以启动 dev server 验证项目运行情况,如果没什么异常就意味着升级完成了,如果升级过程中碰到任何问题,欢迎到 GitHub 讨论区内反馈。