Issue with components using defineAsyncComponent causing navigation and direct link errors in VitePress

[LouisMazel]

Describe the bug

I encounter issues with Vue 3 components that use defineAsyncComponent. The issue manifests differently depending on the component:
• For some components: The problem occurs only during navigation (e.g., navigating to the page from the menu). Directly loading the page (via direct link or page reload) works fine.
• For other components: The problem occurs even when directly loading the page (via direct link or reload).

In both cases, JavaScript errors are thrown, breaking the rendering and navigation. As a result:
• The page content may fail to render.
• Users are blocked from continuing to navigate unless they manually reload the page (which does not always resolve the issue).

This issue significantly impacts the usability of the documentation site.

Screenshot of a navigation bug :

Screenshot of direct link or reload bug :

Code of components :

• MazChecklist : https://github.com/LouisMazel/maz-ui/blob/master/packages/lib/components/MazChecklist.vue
• MazTable : https://github.com/LouisMazel/maz-ui/blob/master/packages/lib/components/MazTable.vue

Reproduction

Navigation bug :

• Go to https://maz-ui.com
• Open the browser console
• Navigate to MazChecklist component documentation page via the menu "components" (https://maz-ui.com/components/maz-checklist)
• The page is not render
• The navigation is broken

Direct Link or Reload bug :

• Go to https://maz-ui.com/components/maz-table
• Open the console
• Reload if you want
• The navigation is broken

Expected behavior

Pages containing components that use defineAsyncComponent should render correctly, regardless of whether they are accessed via navigation or direct link. Navigation should not break, and no JavaScript errors should occur.

System Info

System:
    OS: macOS 15.1.1
    CPU: (10) arm64 Apple M1 Pro
    Memory: 144.42 MB / 16.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 21.2.0 - ~/.nvm/versions/node/v21.2.0/bin/node
    Yarn: 1.22.19 - ~/.yarn/bin/yarn
    npm: 10.2.3 - ~/.nvm/versions/node/v21.2.0/bin/npm
    pnpm: 9.15.0 - ~/Library/pnpm/pnpm
  Browsers:
    Chrome: 131.0.6778.109
    Safari: 18.1.1

Additional context

This issue blocks users from properly viewing and navigating the documentation site. The workaround of manually reloading pages is unreliable, as some pages fail even with direct access.

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]

Those errors are because there is no suspense boundary. But even if you add one via theme, there are few hydration mismatches:

These are because of invalid html. You're adding a div inside table which is invalid HTML.

[brc-dd]

Apply this patch:

diff --git a/packages/docs/docs/.vitepress/theme/components/Layout.vue b/packages/docs/docs/.vitepress/theme/components/Layout.vue
new file mode 100644
index 0000000..111ad66
--- /dev/null
+++ b/packages/docs/docs/.vitepress/theme/components/Layout.vue
@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import DefaultTheme from 'vitepress/theme'
+</script>
+
+<template>
+  <Suspense>
+    <DefaultTheme.Layout />
+  </Suspense>
+</template>
diff --git a/packages/docs/docs/.vitepress/theme/index.ts b/packages/docs/docs/.vitepress/theme/index.ts
index 43ae43e..6156cba 100644
--- a/packages/docs/docs/.vitepress/theme/index.ts
+++ b/packages/docs/docs/.vitepress/theme/index.ts
@@ -1,6 +1,7 @@
 import type { AosOptions, ToasterOptions } from 'maz-ui'
-import { getAosInstance, installAos, installDialog, installToaster, installWait, vFullscreenImgInstall } from 'maz-ui'
+import type { Theme } from 'vitepress'
 
+import { getAosInstance, installAos, installDialog, installToaster, installWait, vFullscreenImgInstall } from 'maz-ui'
 import * as components from 'maz-ui/components'
 import { inBrowser } from 'vitepress'
 import googleAnalytics from 'vitepress-plugin-google-analytics'
@@ -9,20 +10,19 @@ import DefaultTheme from 'vitepress/theme-without-fonts'
 import { watch } from 'vue'
 
 import ColorContainer from './components/ColorContainer.vue'
-
 import ComponentDemo from './components/ComponentDemo.vue'
-
 import DemoAuthPage from './components/DemoAuthPage.vue'
 import DemoDashboardPage from './components/DemoDashboardPage.vue'
 import DemoProductPage from './components/DemoProductPage.vue'
+import Layout from './components/Layout.vue'
 import NpmBadge from './components/NpmBadge.vue'
 import 'maz-ui/tailwindcss/tailwind.css'
-// import 'maz-ui/css/main.css'
 import 'maz-ui/modules/plugins/aos/scss/index.scss'
 import './main.css'
 
-const theme: typeof DefaultTheme = {
-  ...DefaultTheme,
+export default {
+  extends: DefaultTheme,
+  Layout,
   enhanceApp(ctx) {
     googleAnalytics({
       id: 'G-EM35TM23ZC',
@@ -73,6 +73,4 @@ const theme: typeof DefaultTheme = {
       },
     )
   },
-}
-
-export default theme
+} satisfies Theme

For the hydration mismatches, run:

DEBUG=true pnpm -F=docs build && pnpm -F=docs preview

Then you can see the issues on browser dev consoles and inspect server rendered markup using https://validator.w3.org/#validate_by_input. Alternatively, since you already have a nuxt playground you can use https://github.com/nuxt-modules/html-validator and review your components.

[LouisMazel]

Hooo, you rocks!

Thanks a lot for your time and quick response.
I will apply this fix and deal with the hydration issues!

After testing with this fix, the MazChecklist error in his documentation page seems to come from something else (not from the async component).

[brc-dd]

the MazChecklist error in his documentation page seems to come from something else

Doesn't seem to happen locally after adding Suspense 👀

Screen.Recording.2024-12-10.at.8.42.01.PM.mov

---

PS: Also it seems that you're (intentionally?) leaking your GitHub PAT.

It might be better to use something like this instead - https://ungh.cc/repos/LouisMazel/maz-ui

[LouisMazel]

It's a little bit strange, I still have the MazChecklist error when I build and preview locally...

It's a token key without any permission, just reading the star. But you're right, I should use ungh.cc for sure!
Thank you!

[brc-dd]

Hmm, very weird. Can you maybe push your changes to some branch and I can check again locally?

[LouisMazel]

Yes for sure, you can checkout the branch fix/docs-async-components

The PR: LouisMazel/maz-ui#1193

[brc-dd]

Hmm, still not happening for me 😅

Maybe try git clean -ffxd; pnpm i; pnpm -F=docs build; pnpm -F=docs preview and checking once on incognito or do hard reload?

Don't run git clean if you've local files. Try manually deleting node_modules, .vitepress/dist, .vitepress/.cache, .vitepress/.temp directories instead 👀

[LouisMazel]

After cleaning the cache, all is good!
Again, thank you so much for your help and your time!

I let you close the ticket? I think that's it for me. I just need to fix my hydration warnings :)