[RFC] route meta supports lazy loading

[PeachScript]

背景

dumi 2 提供了全文搜索以及 demo 渲染/源码展示/独立打开的能力，背后的数据都存在全局的 Context 中，当初这样设计的原因是：

1. 文本数据可以做到搜索和展示公用一份
2. demo 数据也可以被搜索到
3. 异步数据会带来额外的状态维护成本，而数据全部放在全局的 Context 可以降低实现复杂度

但 dumi 2 已经被应用于大型文档站点，比如 Ant Design 官网和隐语官网，目前的设计会导致 entry chunk 过大，页面首次加载的白屏时间过长，而且随着文档内容的增加这个情况可能会更加严重，所以需要重新调整路由 meta 数据的加载方案。

当前方案是怎么工作的

在编译时，dumi 会动态生成一个 meta.ts 的临时文件：

dumi/src/features/meta.ts

Lines 54 to 56 in fc4be89

	`{{#metaFiles}}
	import { demos as dm{{{index}}}, frontmatter as fm{{{index}}}, toc as toc{{{index}}}, texts as txt{{{index}}} } from '{{{file}}}?type=meta';
	{{/metaFiles}}

它会通过特殊的 loader 加载每个路由的 3 类数据，分别是：

1. demos：当前路由的 demo 数据，包含 demo 源代码、元信息和实际渲染的组件
2. frontmatter：当前路由的 FrontMatter 数据，包含 Markdown 文档头部配置的值及一些内置值（比如 filename、lastUpdated 等）
3. toc：当前路由的标题数据
4. texts：当前路由的文本数据

在运行时初始化阶段，dumi 会通过运行时插件将 2、3、4 类数据 patch 到路由表里，这份数据会存储在 Umi 的 AppContext 里，后续通过路由相关的钩子可以拿到：

dumi/src/features/meta.ts

Lines 108 to 133 in fc4be89

	export const patchRoutes = ({ routes }) => {
	Object.values(routes).forEach((route) => {
	if (filesMeta[route.id]) {
	if (process.env.NODE_ENV === 'production' && (route.meta?.frontmatter?.debug || filesMeta[route.id].frontmatter.debug)) {
	// hide route in production which set hide frontmatter
	delete routes[route.id];
	} else {
	// merge meta to route object
	route.meta = deepmerge(route.meta, filesMeta[route.id]);
	// apply real tab data from id
	route.meta.tabs = route.meta.tabs?.map((id) => {
	const meta = {
	frontmatter: { title: tabs[id].title },
	toc: [],
	texts: [],
	}
	return {
	...tabs[id],
	meta: filesMeta[id] || meta,
	}
	});
	}
	}
	});
	}

以及通过 ContextProvider 将 demos 数据放置在 dumi 的全局 SiteContext 里，后续通过 useSiteData 可以拿到：

dumi/src/features/theme/index.ts

Lines 410 to 416 in f84b043

	<SiteContext.Provider value={{
	pkg: ${JSON.stringify(
	lodash.pick(api.pkg, ...Object.keys(PICKED_PKG_FIELDS)),
	)},
	historyType: "${api.config.history?.type || 'browser'}",
	entryExports,
	demos,

在运行时的消费阶段，一共有 4 处地方会使用这些数据：

1. 侧边栏及导航数据的生成，会使用到 route.meta.frontmatter：

   dumi/src/client/theme-api/useSidebarData.ts

   Line 90 in 4ffe77e

   route.meta.frontmatter,

2. 全站搜索索引的构造，会使用到上述全部数据：

   dumi/src/client/theme-api/useSiteSearch/index.ts

   Lines 71 to 78 in d0decb2

   	worker.postMessage({
   	action: 'generate-metadata',
   	args: {
   	routes: JSON.parse(JSON.stringify(routes)),
   	nav: navData,
   	demos: demoData,
   	},
   	});

3. demo 的渲染及源码展示：

   dumi/src/client/theme-api/DumiDemo.tsx

   Lines 41 to 43 in bc79d2c

   	const { demos, historyType } = useSiteData();
   	const { basename } = useAppData();
   	const { component, asset } = demos[props.demo.id];

4. demo 的独立页面渲染：

   dumi/src/client/pages/Demo/index.ts

   Line 7 in e68fa97

   const { demos } = useSiteData();

如何解决当下面对的问题

大方向就是，把首屏用不到的数据都拆分到异步 chunk 中，等需要使用的时候再加载，具体方案将逐一说明。

首先需要把上述数据做拆分：

1. 由于 FrontMatter 数据需要用来生成导航，所以它是不能被拆分的，也就是说 meta.ts 里 frontmatter 数据仍要保留，对应的运行时插件里 frontmatter 数据的 patch 逻辑也要保留
2. 其余数据要拆分 loader type（目前是 type=meta，可以分成 type=frontmatter、type=demo 和 type=text）来单独加载，loader 逻辑可以复用，因为 dumi 有持久缓存多次加载应该不会影响性能

然后需要明确放入异步 chunk 的方案及加载时机，目前的想法是借用路由自己的 chunk 来加载自己的数据，具体到实现层面有 2 个改造要点：

1. 在 Markdown loader 的注册环节，需要设法把页面的 Markdown Tab 数据以 key: value 形式（key 为页面路由文件，value 为对应的 tab 文件数组）作为参数传进去，用于下一步实现
2. 在 Markdown loader 生成页面组件代码的时候，在顶部把自己及附属 Tab 页面的 meta 数据 import 进来，并且将引入的 texts 数据为自己所用：

   dumi/src/loaders/markdown/index.ts

   Lines 118 to 136 in 8873af2

   	import React from 'react';
   	${
   	isTabContent
   	? `import { useTabMeta } from 'dumi';`
   	: `import { DumiPage, useRouteMeta } from 'dumi';`
   	}
   	// export named function for fastRefresh
   	// ref: https://github.com/pmmmwh/react-refresh-webpack-plugin/blob/main/docs/TROUBLESHOOTING.md#edits-always-lead-to-full-reload
   	function DumiMarkdownContent() {
   	const { texts: ${CONTENT_TEXTS_OBJ_NAME} } = use${
   	isTabContent ? 'TabMeta' : 'RouteMeta'
   	}();
   	return ${isTabContent ? ret.content : `<DumiPage>${ret.content}</DumiPage>`};
   	}
   	export default DumiMarkdownContent;`;
   	}
   	}

放在页面组件 chunk 而不单独拆 chunk 的原因是，页面组件自身的 chunk 代码量其实很少，数据反而是大头，这俩被同时加载的概率又很大（除了搜索时只需要数据不需要页面），所以放在一起可以用尺寸换网络请求数。

接着要确定运行时数据获取的方案调整：

1. dumi 导出 getRouteMetaById 方法，用于异步获取指定路由的 meta 数据，也会成为已有 hook useRouteMeta 和 useTabMeta 的底层方法
2. dumi 导出 getDemoById 方法，用于异步获取指定 demo 的 meta 数据及组件，需要记录 demo id 与 chunk 间的关系实现 demo 数据异步加载，demo id 与 chunk 间的关系可能得新做一个 loader type 来实现，比如 type=demo-index
3. dumi 导出 getAllRoutesMeta 方法，用于异步获取全量路由的 meta 数据
4. dumi 原有路由表内的 texts 和 toc 字段变为空数组，并利用 Proxy 加上废弃提示
5. dumi 原有 SiteContext 中的 demos 字段变为空对象，并利用 Proxy 加上废弃提示
6. dumi 原有 DumiDemo 组件中改为使用 getDemoById 获取 demo 渲染数据

最后是处理其他需要异步获取数据的情况，目前看下来就只有搜索框聚焦及 demo 单独打开这两个场景需要依赖页面异步 chunk 中的数据：

1. 搜索框聚焦：改造 useSiteSearch hook，异步调用 getAllRoutesMeta API 获取所有数据，并完成序列化后传给 worker 建立搜索索引
2. demo 单独打开：改造 pages/Demo/index.ts，异步调用 getDemoById 的方法获取对应的 demo 数据

后续优化点

1. 约定式 tab 页的数据拆成独立 chunk 做按需加载
2. demo 的元数据继续拆元数据和组件的 chunk，这样 demo 独立加载页面就可以只引入组件
3. 搜索的异步 chunk 在首屏完成后自动做 prefetch 预加载

任务拆分

一共分为 4 类任务，各类任务之间理论上是弱耦合，可以通过捏造数据调试：

loader 拆分

任务列表：

• Markdown loader type=meta 拆分为 4 个 type，分别是：
  • demo：返回页面的 demo 数据，数据结构与现在一致
  • demo-index：新增，返回该页面的 demo id 集合，用于根据 demo id 加载对应的 chunk 数据，结构类似 { ids: [...], getter: () => await import('/path/to/xx.md?type=demo') }
  • frontmatter：返回页面的 FrontMatter 数据，数据结构与现在一致
  • text：返回页面的文本数据，包含 texts 和 toc 数据，数据结构与现在一致
• Markdown loader 注册时的 query 拆分（onResolveDemos 和 onResolveAtomMeta 参数挪到默认模式里执行，因为只需要执行一次）

调试方式：

1. 在 example/normal 下创建 .dumi/pages/loader-test.tsx 编写类似内容：

import * as demos from '/path/to/xxx.md?type=demo';

console.log(demos);
export default () => null;

2. 在 example/normal 下执行 pnpm dev 并访问 /loader-test 页面查看控制台内容是否符合预期

页面组件改造

任务列表：

• Markdown loader 注册时需要构造 Markdown 页面与附属 Tabs 的 key: value 数据并传入，该数据已存在，通过 api.appData 共享给 compile 插件即可
• Markdown loader 页面组件改造：
  • 引入自身的 meta 数据实现自包含
  • 将引入的 texts 数据为自己所用，替换原有对 useRouteMeta 和 useTabMeta 的调用

调试方式：

1. 如果 loader 拆分还没 ready，那么在 loader 返回值里伪造 import texts from '/path/to/xx.md?type=text' 的引入值，比如声明 const texts = [...] or const tab1Texts = [...]
2. 在 example/normal 下执行 pnpm dev
3. 查看 Markdown 页面的文本内容是否是 mock 的值
4. 查看 Markdown 页面 Tab 的文本内容是否是 mock 的值

meta 临时文件生成改造

• meta.ts 改造，改造点：
  • 只有 frontmatter 数据保持同步引入，其他数据均放置在各个方法中异步引入
  • 实现 getAllRoutesMeta 方法，异步以 key:value 形式返回所有路由的 meta 数据 { [id]: { texts, toc, frontmatter } }，并通过 exports.ts 导出成为 Theme API
  • 实现 getRouteMetaById 方法，异步返回指定 id 对应的路由数据 { texts, toc, frontmatter }，并通过 exports.ts 导出成为 ThemeAPI
  • 实现 getDemoById 方法，异步返回指定 demo id 对应的 demo 数据{ component: 页面组件, asset: 元数据 }，并通过 exports.ts 导出成为 ThemeAPI（demo 与 chunk 的对应关系依赖 loader 拆分中的 demo-index 数据）

调试方式：

1. 如果 loader 拆分还没 ready，那么在 meta.ts 生成临时文件的内容中伪造 import dmi from '/path/to/xx.md?type=demo-index' 的返回值，数据结构参考上面的任务描述
2. 在 example/normal 下创建 .dumi/pages/api-test.tsx 编写类似内容：

import { getAllRoutesMeta, getRouteMetaById, getDemoById } from 'dumi';

console.log(getAllRoutesMeta());
console.log(getRouteMetaById(xx)); // xx 可以从 `.dumi/tmp/core/route.ts` 里找一个 Markdown 路由的 id
console.log(getDemoById('foo-demo-0'));

3. 在 example/normal 下执行 pnpm dev 并访问 /api-test 页面
4. 分别测试这三个 API 对应的 chunk 是否正常加载，以及期望的数据是否正确返回

运行时 API 改造

任务列表：

• SiteContext 的 demos 字段变为空对象，并利用 Proxy 加上废弃提示
• meta.ts 的运行时插件 中对路由表 texts 和 toc 字段的设置变为空数组，并利用 Proxy 加上废弃提示
• 改造 useRouteMeta 和 useTabMeta，改为基于 getRouteMetaById API 实现
• 改造 DumiDemo 组件，对 demos 的获取逻辑改为基于 getDemoById API 实现

调试方式：

1. 如果 meta 临时文件生成改造还没 ready，那么可以在对应调用的地方 mock getRouteMetaById 和 getDemoById 的 API 返回值，数据结构参考上面的任务描述
2. 在 example/normal 下创建 docs/runtime-test.md 编写类似内容：

```tsx
import { useRouteMeta, useTabMeta, useAppData, useSiteData, DumiDemo } from 'dumi';

export default () => {
  console.log(useRouteMeta());
  console.log(useSiteData().demos);
  console.log(useAppData().clientRoutes.[..]);

  return 
}
```

3. 在 example/normal 下创建 docs/runtime-test.$tab-a.md 编写类似内容：

```tsx
import { useTabMeta } from 'dumi';

export default () => {
  console.log(useTabMeta());
}
```

4. 在 example/normal 下执行 pnpm dev 并访问 /runtime-test 页面，验证 hook 的 Proxy 警告是否正常展示，验证 hook 的返回值是否正常，验证 DumiDemo 是否正常渲染
5. 访问/runtime-test?tab=a 页面，验证 hook 返回值是否正常

协同流程

1. 基于 master 切出新分支做开发
2. 完成后提交 PR 至该分支：https://github.com/umijs/dumi/tree/feature/2.3.0
3. 待所有功能研发完毕后 2.3.0 分支统一提 PR 合并 master，然后发布新版本

时间点

• 09.30 发布 2.3.0 + Breaking Change (maybe)

暂时想到这些，如有遗漏欢迎补充

[MadCcc]

builtin 等内置组件不会被搜索引擎收集的问题有解吗

[PeachScript]

这个 RFC 没有解这个问题

[zombieJ]

Task 里有对应的文件不，对 dumi 不熟悉看着会有点懵。另外，这个 Task 是独立的 PR 还是要一起做完才能跑？

[PeachScript]

任务加上对应文件的链接了，以及对任务做了分类，各个分类间的任务是弱耦合，可以独立开发 + 捏造数据进行调试

[MadCcc]

先 own 一下

@MadCcc

• loader 拆分
• 页面组件改造

@zombieJ

• meta 临时文件生成改造
• 运行时 API 改造

[zombieJ]

loader: demo-index 这个好像有点问题。单独打开的页面，它只有 demo id 没有 route 信息。不知道从哪里去加载。

[PeachScript]

demo-index 的返回值是 { ids: string[]; getter: () => ({ [demo.id]: { demo: React.Component, ... }, ... }) }，封装的 getDemoById 方法根据 ids 的匹配执行对应的 getter 就会自动请求对应 chunk 拿到对应模块，至于模块是合并到页面 chunk 还是单独拆，可以调整 Code Splitting 策略来控制

[PeachScript]

feature/2.3.0 分支 route meta 异步加载的调整计划：

1. 临时文件调整
   a. templates 下面用文件夹替代前缀作为分组
   b. 循坏生成的内容 key 统一用单字母，尽可能减小产物尺寸，比如 textGetter => t，暂时不改，gzip 后差距应该不大
   c. 新增 meta/exports.ts，专门用来放置要通过 dumi 导出的方法，将 getRouteMetaById、getDemoById、loadFilesMeta 的实现都挪过来，便于维护
   d. meta-route.ts、meta-frontmatter.ts 及 meta-search.ts 中的索引合并到 meta/files.ts，节省 id 尺寸及便于维护
   e. loadFilesMeta => getAllRoutesMeta，并在运行时循环处理 metaFiles 降低产物尺寸
2. 运行时 API 部分：
   a. useSiteSearch 新增 status，枚举值为 'preparing' | 'searching' | 'done'，用于 SearchResult 区分是异步数据加载中还是搜索中，目前是 再存了一份 state 来实现数据加载中不展示 loading，后续维护理解起来有成本，原 loading 仍然保留避免 Breaking Change
   b. getDemoById 不暴露在 context 中，统一从 dumi 引入使用
   c. useDemoData => useDemo，变成单独的文件维护
   d. context/use.ts => context/utils.ts，和 utils 维护在一起
   e. useRouteMeta 和 useTabMeta 支持两种模式，默认为异步模式，借助 suspense 加载数据后再渲染，同步模式下仅返回 frontmatter 用于 Helmet 的场景
   f. getAllRoutesMeta 的返回值包含 tabs 数据，这样可以将 tabs 数据从 context 中去除
3. 其他：
   a. compile.ts 使用 /**/ 来优化 webpack-chain 的缩进，提升可读性
   b. chunkName 的逻辑看是否能复用 Umi 层的

[PeachScript]

feature/2.3.0 分支 live demo 的调整...

已移动至独立的 RFC：#1991