enhanceApp 异步导入组件库 进行客户端组件渲染 文档打包后第一次进入组件示例 首页视图残留

[FengyangMK]

Describe the bug

背景:
由于特殊的需求团队使用element-plus等第三方组件库进行内部组件库封装, vitepress进行文档示例编写。由于内部组件库内大量使用浏览器api和第三方库导致vitepress直接使用组件库的npm包会出现打包失败的问题 ，为此我们不得不额外维护一个针对vitepress SSR场景的组件库npm包
问题:

1. 依据官方文档 Theme.enhanceApp 的说明异步的导入组件库npm包时 它可以解决我打包失败的问题;
2. 但执行preview 预览打包后的产物时 第一次直接进入Component examples 首页的视图会残留 而且文档内容区域表现异常
3. 这个现象当且只在第一次进入示例界面出现 刷新当前异常示例界面 界面视图恢复正常

Reproduction

我在stackblitz中 使用Element-plus 作为打包测试的目标 打包构建预览后没有复现我的问题 但是在本地vscode中 同样的代码配置进行预览它可以复现我的问题 若您没有在stackblitz复现 麻烦请在本地进行测试
https://stackblitz.com/edit/vite-pkx6x3v1?file=docs%2Findex.md,docs%2F.vitepress%2Fconfig.ts,docs%2Fmarkdown-examples.md,docs%2Fdemos%2Fbase.vue,docs%2F.vitepress%2Ftheme%2Findex.ts
步骤:
文档打包进行本地浏览器预览 直接在首页点击进入Component Examples界面

Expected behavior

第一次进入Component Examples界面 首页的视图会残留 而且文档内容区域表现异常

System Info

System:
    OS: macOS 15.2
    CPU: (8) arm64 Apple M1 Pro
    Memory: 66.73 MB / 16.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 20.12.2 - ~/.nvm/versions/node/v20.12.2/bin/node
    Yarn: 1.22.22 - ~/.nvm/versions/node/v20.12.2/bin/yarn
    npm: 10.7.0 - ~/.nvm/versions/node/v20.12.2/bin/npm
    pnpm: 9.1.1 - ~/.nvm/versions/node/v20.12.2/bin/pnpm
  Browsers:
    Chrome: 132.0.6834.160
    Safari: 18.2
  npmPackages:
    vitepress: latest => 1.6.3

Additional context

Validations

• Check if you're on the latest VitePress version.
• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

[brc-dd]

Not happening with me locally either.

Screen.Recording.2025-02-04.at.1.24.47.PM.mov

Can you check your browser console? Some request might be getting blocked by extensions or something.

[FengyangMK]

Not happening with me locally either.

Screen.Recording.2025-02-04.at.1.24.47.PM.mov
Can you check your browser console? Some request might be getting blocked by extensions or something.

20250205_100618.mp4

浏览器第一次访问http://localhost:4173/ 站点， 浏览器控制台显示 framework.Dh8mGfz4.js:13 Hydration completed but contains mismatches. 界面刷新后正常。

我使用工作电脑复现了问题

System:
OS: Windows 11 10.0.22631
CPU: (12) x64 13th Gen Intel(R) Core(TM) i7-1355U
Memory: 14.09 GB / 31.69 GB
Binaries:
Node: 18.20.5 - C:\Program Files\nodejs\node.EXE
Yarn: 1.22.22 - C:\Program Files\nodejs\yarn.CMD
npm: 10.8.2 - C:\Program Files\nodejs\npm.CMD
pnpm: 9.15.1 - C:\Program Files\nodejs\pnpm.CMD
Browsers:
Edge: Chromium (127.0.2651.86)
Internet Explorer: 11.0.22621.3527

[brc-dd]

Hmm, very weird. Can you try running this and checking the browser console again:

If using cmd:

set DEBUG=true
npm run docs:build
npm run docs:preview

If using powershell, replace first line by $env:DEBUG = "true" in above.

Then check the browser dev console again. That demo plugin you're using might have some compatibility issue with Windows.

[FengyangMK]

Hmm, very weird. Can you try running this and checking the browser console again:

If using cmd:

set DEBUG=true
npm run docs:build
npm run docs:preview
If using powershell, replace first line by $env:DEBUG = "true" in above.

Then check the browser dev console again. That demo plugin you're using might have some compatibility issue with Windows.
在这个版本中我移除了演示插件
https://stackblitz.com/edit/vite-bqjesnuz?file=docs%2Findex.md,docs%2Fdemos%2Fbase.vue,docs%2F.vitepress%2Ftheme%2Findex.ts,package.json,docs%2Fvite.config.ts,docs%2F.vitepress%2Ftheme%2Fstyle.css,docs%2F.vitepress%2Fconfig.ts

当我在本地依据您的要求运行脚本命令后 问题仍然存在
https://github.com/user-attachments/assets/e88b17b5-ff3b-48bb-a41f-23201c64d9b8

请清除浏览器数据 在无痕窗口下测试 进入预览网址后不要刷新浏览器 直接在首页点击进入Component Examples界面

[brc-dd]

This is happening when you interact before the JS execution has completed. If you wait for few seconds before clicking that link it works fine. I don't think the bug is with vitepress. That demo plugin is doing weird stuff by bundling node code in client.

Edit: It's happening without that plugin too. IIRC element-plus needs preloading some links to work properly.

One way can be to do something like this (i.e. avoid dynamic import, conditional dynamic import is necessary only when using something that uses browser APIs on import):

import { install } from 'element-plus'
import { inBrowser, type Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

import 'element-plus/dist/index.css'
import './style.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app, router, siteData }) {
    inBrowser && install(app)
  }
} satisfies Theme

Also, element-plus is SSR compatible. So you can do:

import plugin, { ID_INJECTION_KEY, ZINDEX_INJECTION_KEY } from 'element-plus'
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

import 'element-plus/dist/index.css'

import './style.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.use(plugin)
    app.provide(ID_INJECTION_KEY, { prefix: 1024, current: 0 })
    app.provide(ZINDEX_INJECTION_KEY, { current: 0 })
  }
} satisfies Theme

[FengyangMK]

Thank you for your answer

[Zhang-Wei-666]