feat: dynamic routes plugin overhaul (#4525)

BREAKING CHANGES: Internals are modified a bit to better support vite 6 and handle HMR more correctly. For most users this won't need any change on their side.

Author: brc-dd

__tests__/e2e/dynamic-routes/[id].paths.ts

@@ -1,8 +1,14 @@
-export default {
-  async paths() {
-    return [
-      { params: { id: 'foo' }, content: `# Foo` },
-      { params: { id: 'bar' }, content: `# Bar` }
-    ]
+import { defineRoutes } from 'vitepress'
+import paths from './paths'
+
+export default defineRoutes({
+  async paths(watchedFiles: string[]) {
+    // console.log('watchedFiles', watchedFiles)
+    return paths
+  },
+  watch: ['**/data-loading/**/*.json'],
+  async transformPageData(pageData) {
+    // console.log('transformPageData', pageData.filePath)
+    pageData.title += ' - transformed'
   }
-}
+})

__tests__/e2e/dynamic-routes/paths.ts

@@ -0,0 +1,4 @@
+export default [
+  { params: { id: 'foo' }, content: `# Foo` },
+  { params: { id: 'bar' }, content: `# Bar` }
+]

__tests__/unit/node/utils/moduleGraph.test.ts

@@ -0,0 +1,72 @@
+import { ModuleGraph } from 'node/utils/moduleGraph'
+
+describe('node/utils/moduleGraph', () => {
+  let graph: ModuleGraph
+
+  beforeEach(() => {
+    graph = new ModuleGraph()
+  })
+
+  it('should correctly delete a module and its dependents', () => {
+    graph.add('A', ['B', 'C'])
+    graph.add('B', ['D'])
+    graph.add('C', [])
+    graph.add('D', [])
+
+    expect(graph.delete('D')).toEqual(new Set(['D', 'B', 'A']))
+  })
+
+  it('should handle shared dependencies correctly', () => {
+    graph.add('A', ['B', 'C'])
+    graph.add('B', ['D'])
+    graph.add('C', ['D']) // Shared dependency
+    graph.add('D', [])
+
+    expect(graph.delete('D')).toEqual(new Set(['A', 'B', 'C', 'D']))
+  })
+
+  it('merges dependencies correctly', () => {
+    // Add module A with dependency B
+    graph.add('A', ['B'])
+    // Merge new dependency C into module A (B should remain)
+    graph.add('A', ['C'])
+
+    // Deleting B should remove A as well, since A depends on B.
+    expect(graph.delete('B')).toEqual(new Set(['B', 'A']))
+  })
+
+  it('handles cycles gracefully', () => {
+    // Create a cycle: A -> B, B -> C, C -> A.
+    graph.add('A', ['B'])
+    graph.add('B', ['C'])
+    graph.add('C', ['A'])
+
+    // Deleting any module in the cycle should delete all modules in the cycle.
+    expect(graph.delete('A')).toEqual(new Set(['A', 'B', 'C']))
+  })
+
+  it('cleans up dependencies when deletion', () => {
+    // Setup A -> B relationship.
+    graph.add('A', ['B'])
+    graph.add('B', [])
+
+    // Deleting B should remove both B and A from the graph.
+    expect(graph.delete('B')).toEqual(new Set(['B', 'A']))
+
+    // After deletion, add modules again.
+    graph.add('C', [])
+    graph.add('A', ['C']) // Now A depends only on C.
+
+    expect(graph.delete('C')).toEqual(new Set(['C', 'A']))
+  })
+
+  it('handles independent modules', () => {
+    // Modules with no dependencies.
+    graph.add('X', [])
+    graph.add('Y', [])
+
+    // Deletion of one should only remove that module.
+    expect(graph.delete('X')).toEqual(new Set(['X']))
+    expect(graph.delete('Y')).toEqual(new Set(['Y']))
+  })
+})

src/client/app/data.ts

@@ -62,7 +62,7 @@ export const siteDataRef: Ref<SiteData> = shallowRef(
 
 // hmr
 if (import.meta.hot) {
-  import.meta.hot.accept('/@siteData', (m) => {
+  import.meta.hot.accept('@siteData', (m) => {
     if (m) {
       siteDataRef.value = m.default
     }

src/client/theme-default/components/VPLocalSearchBox.vue

@@ -46,7 +46,7 @@ const searchIndexData = shallowRef(localSearchIndex)
 
 // hmr
 if (import.meta.hot) {
-  import.meta.hot.accept('/@localSearchIndex', (m) => {
+  import.meta.hot.accept('@localSearchIndex', (m) => {
     if (m) {
       searchIndexData.value = m.default
     }

src/node/config.ts

@@ -97,20 +97,12 @@ export async function resolveConfig(
     ? userThemeDir
     : DEFAULT_THEME_PATH
 
-  const { pages, dynamicRoutes, rewrites } = await resolvePages(
-    srcDir,
-    userConfig,
-    logger
-  )
-
   const config: SiteConfig = {
     root,
     srcDir,
     assetsDir,
     site,
     themeDir,
-    pages,
-    dynamicRoutes,
     configPath,
     configDeps,
     outDir,
@@ -135,10 +127,10 @@ export async function resolveConfig(
     transformHead: userConfig.transformHead,
     transformHtml: userConfig.transformHtml,
     transformPageData: userConfig.transformPageData,
-    rewrites,
     userConfig,
     sitemap: userConfig.sitemap,
-    buildConcurrency: userConfig.buildConcurrency ?? 64
+    buildConcurrency: userConfig.buildConcurrency ?? 64,
+    ...(await resolvePages(srcDir, userConfig, logger))
   }
 
   // to be shared with content loaders

src/node/index.ts

@@ -5,6 +5,11 @@ export * from './contentLoader'
 export * from './init/init'
 export * from './markdown/markdown'
 export { defineLoader, type LoaderModule } from './plugins/staticDataPlugin'
+export {
+  defineRoutes,
+  type ResolvedRouteConfig,
+  type RouteModule
+} from './plugins/dynamicRoutesPlugin'
 export * from './postcss/isolateStyles'
 export * from './serve/serve'
 export * from './server'

src/node/init/init.ts

@@ -11,7 +11,7 @@ import fs from 'fs-extra'
 import template from 'lodash.template'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { bold, cyan, yellow } from 'picocolors'
+import c from 'picocolors'
 import { slash } from '../shared'
 
 export enum ScaffoldThemeType {
@@ -38,7 +38,7 @@ const getPackageManger = () => {
 }
 
 export async function init(root?: string) {
-  intro(bold(cyan('Welcome to VitePress!')))
+  intro(c.bold(c.cyan('Welcome to VitePress!')))
 
   const options = await group(
     {
@@ -232,7 +232,7 @@ export function scaffold({
   const gitignorePrefix = root ? `${slash(root)}/.vitepress` : '.vitepress'
   if (fs.existsSync('.git')) {
     tips.push(
-      `Make sure to add ${cyan(`${gitignorePrefix}/dist`)} and ${cyan(`${gitignorePrefix}/cache`)} to your ${cyan(`.gitignore`)} file.`
+      `Make sure to add ${c.cyan(`${gitignorePrefix}/dist`)} and ${c.cyan(`${gitignorePrefix}/cache`)} to your ${c.cyan(`.gitignore`)} file.`
     )
   }
 
@@ -242,11 +242,11 @@ export function scaffold({
     !userPkg.devDependencies?.['vue']
   ) {
     tips.push(
-      `Since you've chosen to customize the theme, you should also explicitly install ${cyan(`vue`)} as a dev dependency.`
+      `Since you've chosen to customize the theme, you should also explicitly install ${c.cyan(`vue`)} as a dev dependency.`
     )
   }
 
-  const tip = tips.length ? yellow([`\n\nTips:`, ...tips].join('\n- ')) : ``
+  const tip = tips.length ? c.yellow([`\n\nTips:`, ...tips].join('\n- ')) : ``
   const dir = root ? ' ' + root : ''
   const pm = getPackageManger()
 
@@ -261,8 +261,8 @@ export function scaffold({
     Object.assign(userPkg.scripts || (userPkg.scripts = {}), scripts)
     fs.writeFileSync(pkgPath, JSON.stringify(userPkg, null, 2))
 
-    return `Done! Now run ${cyan(`${pm} run ${prefix}dev`)} and start writing.${tip}`
+    return `Done! Now run ${c.cyan(`${pm} run ${prefix}dev`)} and start writing.${tip}`
   } else {
-    return `You're all set! Now run ${cyan(`${pm === 'npm' ? 'npx' : pm} vitepress dev${dir}`)} and start writing.${tip}`
+    return `You're all set! Now run ${c.cyan(`${pm === 'npm' ? 'npx' : pm} vitepress dev${dir}`)} and start writing.${tip}`
   }
 }

src/node/markdownToVue.ts

@@ -9,6 +9,7 @@ import {
   type MarkdownOptions,
   type MarkdownRenderer
 } from './markdown/markdown'
+import { getPageDataTransformer } from './plugins/dynamicRoutesPlugin'
 import {
   EXTERNAL_URL_RE,
   getLocaleForPath,
@@ -31,25 +32,62 @@ export interface MarkdownCompileResult {
   includes: string[]
 }
 
-export function clearCache(file?: string) {
-  if (!file) {
+export function clearCache(id?: string) {
+  if (!id) {
     cache.clear()
     return
   }
 
-  file = JSON.stringify({ file }).slice(1)
-  cache.find((_, key) => key.endsWith(file!) && cache.delete(key))
+  id = JSON.stringify({ id }).slice(1)
+  cache.find((_, key) => key.endsWith(id!) && cache.delete(key))
+}
+
+let __pages: string[] = []
+let __dynamicRoutes = new Map<string, [string, string]>()
+let __rewrites = new Map<string, string>()
+let __ts: number
+
+function getResolutionCache(siteConfig: SiteConfig) {
+  // @ts-expect-error internal
+  if (siteConfig.__dirty) {
+    __pages = siteConfig.pages.map((p) => slash(p.replace(/\.md$/, '')))
+
+    __dynamicRoutes = new Map(
+      siteConfig.dynamicRoutes.map((r) => [
+        r.fullPath,
+        [slash(path.join(siteConfig.srcDir, r.route)), r.loaderPath]
+      ])
+    )
+
+    __rewrites = new Map(
+      Object.entries(siteConfig.rewrites.map).map(([key, value]) => [
+        slash(path.join(siteConfig.srcDir, key)),
+        slash(path.join(siteConfig.srcDir, value!))
+      ])
+    )
+
+    __ts = Date.now()
+
+    // @ts-expect-error internal
+    siteConfig.__dirty = false
+  }
+
+  return {
+    pages: __pages,
+    dynamicRoutes: __dynamicRoutes,
+    rewrites: __rewrites,
+    ts: __ts
+  }
 }
 
 export async function createMarkdownToVueRenderFn(
   srcDir: string,
   options: MarkdownOptions = {},
-  pages: string[],
   isBuild = false,
   base = '/',
   includeLastUpdatedData = false,
   cleanUrls = false,
-  siteConfig: SiteConfig | null = null
+  siteConfig: SiteConfig
 ) {
   const md = await createMarkdownRenderer(
     srcDir,
@@ -58,32 +96,30 @@ export async function createMarkdownToVueRenderFn(
     siteConfig?.logger
   )
 
-  pages = pages.map((p) => slash(p.replace(/\.md$/, '')))
-
-  const dynamicRoutes = new Map(
-    siteConfig?.dynamicRoutes?.routes.map((r) => [
-      r.fullPath,
-      slash(path.join(srcDir, r.route))
-    ]) || []
-  )
-
-  const rewrites = new Map(
-    Object.entries(siteConfig?.rewrites.map || {}).map(([key, value]) => [
-      slash(path.join(srcDir, key)),
-      slash(path.join(srcDir, value!))
-    ]) || []
-  )
-
   return async (
     src: string,
     file: string,
     publicDir: string
   ): Promise<MarkdownCompileResult> => {
-    const fileOrig = dynamicRoutes.get(file) || file
+    const { pages, dynamicRoutes, rewrites, ts } =
+      getResolutionCache(siteConfig)
+
+    const dynamicRoute = dynamicRoutes.get(file)
+    const fileOrig = dynamicRoute?.[0] || file
+    const transformPageData = [
+      siteConfig?.transformPageData,
+      getPageDataTransformer(dynamicRoute?.[1]!)
+    ].filter((fn) => fn != null)
+
     file = rewrites.get(file) || file
     const relativePath = slash(path.relative(srcDir, file))
 
-    const cacheKey = JSON.stringify({ src, file: relativePath })
+    const cacheKey = JSON.stringify({
+      src,
+      ts,
+      file: relativePath,
+      id: fileOrig
+    })
     if (isBuild || options.cache !== false) {
       const cached = cache.get(cacheKey)
       if (cached) {
@@ -205,14 +241,14 @@ export async function createMarkdownToVueRenderFn(
       }
     }
 
-    if (siteConfig?.transformPageData) {
-      const dataToMerge = await siteConfig.transformPageData(pageData, {
-        siteConfig
-      })
-      if (dataToMerge) {
-        pageData = {
-          ...pageData,
-          ...dataToMerge
+    for (const fn of transformPageData) {
+      if (fn) {
+        const dataToMerge = await fn(pageData, { siteConfig })
+        if (dataToMerge) {
+          pageData = {
+            ...pageData,
+            ...dataToMerge
+          }
         }
       }
     }
@@ -318,10 +354,7 @@ const inferDescription = (frontmatter: Record<string, any>) => {
   return (head && getHeadMetaContent(head, 'description')) || ''
 }
 
-const getHeadMetaContent = (
-  head: HeadConfig[],
-  name: string
-): string | undefined => {
+const getHeadMetaContent = (head: HeadConfig[], name: string) => {
   if (!head || !head.length) {
     return undefined
   }