fix(docs|unconfig-vitepress): hydration mismatches issues in some pages, missing components, and bad layout slots renderer (#111)

Signed-off-by: Neko Ayaka <[email protected]>

Author: nekomeowww

.github/workflows/ci-build.yaml

@@ -65,10 +65,20 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Build packages
+        run: pnpm packages:build
+        env:
+          # As suggested in Verbose Build option to be able to track down errors https://github.com/vuejs/vitepress/issues/422
+          # vitepress build command does not have --debug option, so we need to set it manually where the debug package is used.
+          DEBUG: '*'
+
       - name: Build docs
-        run: |
-          pnpm packages:build
-          pnpm docs:build
+        run: pnpm docs:build
+        env:
+          # As suggested in Verbose Build option to be able to track down errors https://github.com/vuejs/vitepress/issues/422
+          # vitepress build command does not have --debug option, so we need to set it manually where the debug package is used.
+          DEBUG: 'vitepress:*'
+          VUE_PROD_HYDRATION_MISMATCH_DETAILS_FLAG: '1'
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4

docs/.vitepress/config.ts

@@ -1,4 +1,4 @@
-import { cwd } from 'node:process'
+import { cwd, env } from 'node:process'
 import { join, relative } from 'node:path'
 import { type DefaultTheme, defineConfig } from 'vitepress'
 import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'
@@ -83,8 +83,22 @@ export const sidebars: Record<string, DefaultTheme.Sidebar> = {
   ],
 }
 
+function getVueProdHydrationMismatchDetailsFlag() {
+  if (!env) {
+    console.warn('WARNING: env is not available when trying to get Vue Prod Hydration Mismatch Details Flag')
+    throw new Error('env is not available')
+  }
+
+  return !!env.VUE_PROD_HYDRATION_MISMATCH_DETAILS_FLAG
+}
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
+  vite: {
+    define: {
+      __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: getVueProdHydrationMismatchDetailsFlag(),
+    },
+  },
   lastUpdated: true,
   themeConfig: {
     outline: 'deep',

docs/vite-env.d.ts

@@ -0,0 +1,10 @@
+// Env Variables and Modes | Vite
+// https://vitejs.dev/guide/env-and-mode#intellisense-for-typescript
+
+interface ImportMetaEnv {
+  readonly VUE_PROD_HYDRATION_MISMATCH_DETAILS_FLAG?: '1'
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

docs/vite.config.ts

@@ -1,16 +1,33 @@
-import { join, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { env } from 'node:process'
 import { defineConfig } from 'vite'
 import UnoCSS from 'unocss/vite'
 import Inspect from 'vite-plugin-inspect'
 import { GitChangelog, GitChangelogMarkdownSection } from '@nolebase/vitepress-plugin-git-changelog/vite'
 import { PageProperties, PagePropertiesMarkdownSection } from '@nolebase/vitepress-plugin-page-properties/vite'
 
+function getVueProdHydrationMismatchDetailsFlag() {
+  if (!env) {
+    console.warn('WARNING: env is not available when trying to get Vue Prod Hydration Mismatch Details Flag')
+    throw new Error('env is not available')
+  }
+
+  return !!env.VUE_PROD_HYDRATION_MISMATCH_DETAILS_FLAG
+}
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
 export default defineConfig({
   assetsInclude: [
     '**/*.mov',
     '**/*.mp4',
     '**/*.riv',
   ],
+  define: {
+    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: getVueProdHydrationMismatchDetailsFlag(),
+  },
   resolve: {
     alias: {
       '@nolebase/ui': resolve(__dirname, '../packages/ui/src/'),

packages/vitepress-plugin-git-changelog/package.json

@@ -54,20 +54,17 @@
     "build": "unbuild"
   },
   "peerDependencies": {
-    "dayjs": ">=1.11.1",
-    "md5": ">=2.3.0",
-    "simple-git": ">=3.21.0",
     "vitepress": ">=1.0.0-rc.44"
   },
   "dependencies": {
     "@iconify-json/octicon": "^1.1.52",
     "@nolebase/ui": "workspace:^",
-    "dayjs": "^1.11.10",
-    "md5": "^2.3.0"
-  },
-  "devDependencies": {
-    "builtin-modules": "^3.3.0",
     "date-fns": "^3.3.1",
+    "md5": "^2.3.0",
     "simple-git": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/md5": "^2.3.5",
+    "builtin-modules": "^3.3.0"
   }
 }

packages/vitepress-plugin-git-changelog/src/client/components/Changelog.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, inject, ref } from 'vue'
+import { computed, inject, onMounted, ref } from 'vue'
 import { differenceInDays, toDate } from 'date-fns'
 import { useData } from 'vitepress'
 
@@ -23,27 +23,25 @@ const { t } = useI18n()
 const rawPath = useRawPath()
 const commits = useCommits(Changelog.commits, rawPath)
 
+const lastChangeDate = ref<Date>(toDate(commits.value[0]?.date_timestamp))
+
 const locale = computed<Locale>(() => {
   if (!options.locales || typeof options.locales === 'undefined')
     return defaultLocales[lang.value] || defaultEnLocale || {}
 
   return options.locales[lang.value] || defaultEnLocale || {}
 })
 
-const lastChangeDate = computed(() => {
-  const dateTimestamp: number = commits.value[0]?.date_timestamp || 0
-  if (!dateTimestamp)
-    return new Date()
-
-  return toDate(dateTimestamp)
-})
-
 const isFreshChange = computed(() => {
   if (!lastChangeDate.value)
     return false
 
   return differenceInDays(new Date(), lastChangeDate.value) < 1
 })
+
+onMounted(() => {
+  lastChangeDate.value = toDate(commits.value[0]?.date_timestamp)
+})
 </script>
 
 <template>
@@ -102,9 +100,11 @@ const isFreshChange = computed(() => {
               <a :href="commit.release_tag_url" target="_blank">
                 <code class="font-bold">{{ commit.tag }}</code>
               </a>
-              <span class="text-xs opacity-50">
-                {{ t('committedOn', { props: { date: new Date(commit.date).toLocaleDateString() } }) }}
-              </span>
+              <ClientOnly>
+                <span class="text-xs opacity-50" :title="toDate(commit.date_timestamp).toString()">
+                  {{ t('committedOn', { props: { date: toDate(commit.date_timestamp).toLocaleDateString() } }) }}
+                </span>
+              </ClientOnly>
             </div>
           </template>
           <template v-else>
@@ -122,9 +122,11 @@ const isFreshChange = computed(() => {
               <span>-</span>
               <span>
                 <span class="text-sm <sm:text-xs" v-html="renderCommitMessage(commit.repo_url || 'https://github.com/example/example', commit.message)" />
-                <span class="text-xs opacity-50">
-                  {{ t('committedOn', { props: { date: new Date(commit.date).toLocaleDateString() } }) }}
-                </span>
+                <ClientOnly>
+                  <span class="text-xs opacity-50" :title="toDate(commit.date_timestamp).toString()">
+                    {{ t('committedOn', { props: { date: toDate(commit.date_timestamp).toLocaleDateString() } }) }}
+                  </span>
+                </ClientOnly>
               </span>
             </div>
           </template>

packages/vitepress-plugin-git-changelog/src/client/components/Contributors.vue

@@ -8,6 +8,7 @@ import { useRawPath } from '../composables/path'
 import { useCommits } from '../composables/commits'
 import { useI18n } from '../composables/i18n'
 import { InjectionKey } from '../constants'
+import type { Commit } from '../../types'
 
 interface ContributorInfo {
   name: string

packages/vitepress-plugin-git-changelog/src/client/utils.ts

@@ -1,4 +1,5 @@
 import { formatDistanceToNow, toDate } from 'date-fns'
+import type { Locale } from 'date-fns'
 import * as DateFnsLocales from 'date-fns/locale'
 
 export function renderMarkdown(markdownText = '') {
@@ -24,10 +25,10 @@ export function renderCommitMessage(repoLink: string, msg: string) {
     .replace(/\#([0-9]+)/g, `<a href=\'${repoLink}/issues/$1\'>#$1</a>`)
 }
 
-export function formatDistanceToNowFromValue(value: string | number | Date, localeName = 'enUS') {
+export function formatDistanceToNowFromValue(value: Date, localeName = 'enUS') {
   try {
     return formatDistanceToNow(toDate(value), {
-      locale: DateFnsLocales[localeName] || 'enUS',
+      locale: (DateFnsLocales as Record<string, Locale>)[localeName] || 'enUS',
       addSuffix: true,
     })
   }

packages/vitepress-plugin-git-changelog/src/client/virtual.d.ts

@@ -1,24 +1,10 @@
-interface Commit {
-  path: string[][]
-  tag?: string
-  release_tag_url?: string
-  hash: string
-  hash_url?: string
-  date: string
-  message: string
-  refs?: string
-  body?: string
-  author_name: string
-  author_email: string
-  author_avatar: string
-  repo_url?: string
-}
+declare module 'virtual:nolebase-git-changelog' {
+  import type { Commit } from '../types'
 
-interface Changelog {
-  commits: Commit[]
-}
+  interface Changelog {
+    commits: Commit[]
+  }
 
-declare module 'virtual:nolebase-git-changelog' {
   const changelog: Changelog
   export default changelog
 }

packages/vitepress-plugin-git-changelog/src/types/index.ts

@@ -5,7 +5,7 @@ export interface Commit {
   hash: string
   hash_url?: string
   date: string
-  date_timestamp?: number
+  date_timestamp: number
   message: string
   refs?: string
   body?: string