feat: implement 'as-needed' prefetch and preload strategy with chunk file mapping

packages/bundler-vite/src/build/build.ts

@@ -1,3 +1,4 @@
+import type { PageChunkFilesMap } from '@vuepress/bundlerutils'
 import { createVueServerApp, getSsrTemplate } from '@vuepress/bundlerutils'
 import type { App, Bundler } from '@vuepress/core'
 import { colors, debug, fs, withSpinner } from '@vuepress/utils'
@@ -7,6 +8,7 @@ import { build as viteBuild } from 'vite'
 import { resolveViteConfig } from '../resolveViteConfig.js'
 import type { ViteBundlerOptions } from '../types.js'
 import { renderPage } from './renderPage.js'
+import { resolvePageChunkFiles } from './resolvePageChunkFiles.js'
 
 const log = debug('vuepress:bundler-vite/build')
 
@@ -65,6 +67,15 @@ export const build = async (
     )
     const ssrTemplate = await getSsrTemplate(app)
 
+    // build page path -> chunk files map for preload & prefetch
+    const pageChunkFilesMap: PageChunkFilesMap = new Map()
+    for (const page of app.pages) {
+      pageChunkFilesMap.set(
+        page.path,
+        resolvePageChunkFiles({ page, output: clientOutput.output }),
+      )
+    }
+
     // pre-render pages to html files
     for (const page of app.pages) {
       if (spinner) spinner.text = `Rendering pages ${colors.magenta(page.path)}`
@@ -77,6 +88,7 @@ export const build = async (
         output: clientOutput.output,
         outputEntryChunk: clientEntryChunk,
         outputCssAsset: clientCssAsset,
+        pageChunkFilesMap,
       })
     }
   })

packages/bundler-vite/src/build/renderPage.ts

@@ -1,3 +1,4 @@
+import type { PageChunkFilesMap } from '@vuepress/bundlerutils'
 import { renderPageToString } from '@vuepress/bundlerutils'
 import type { App, Page } from '@vuepress/core'
 import { fs, renderHead } from '@vuepress/utils'
@@ -20,6 +21,7 @@ export const renderPage = async ({
   output,
   outputEntryChunk,
   outputCssAsset,
+  pageChunkFilesMap,
 }: {
   app: App
   page: Page
@@ -29,6 +31,7 @@ export const renderPage = async ({
   output: RolldownOutput['output']
   outputEntryChunk: OutputChunk
   outputCssAsset: OutputAsset | undefined
+  pageChunkFilesMap: PageChunkFilesMap
 }): Promise<void> => {
   // render current page to string
   const { ssrContext, ssrString } = await renderPageToString({
@@ -49,11 +52,15 @@ export const renderPage = async ({
       app,
       outputEntryChunk,
       pageChunkFiles,
+      page,
+      pageChunkFilesMap,
     }),
     preload: renderPagePreloadLinks({
       app,
       outputEntryChunk,
       pageChunkFiles,
+      page,
+      pageChunkFilesMap,
     }),
     scripts: renderPageScripts({ app, outputEntryChunk }),
     styles: renderPageStyles({ app, outputCssAsset }),

packages/bundler-vite/src/build/renderPagePrefetchLinks.ts

@@ -1,4 +1,6 @@
-import type { App } from '@vuepress/core'
+import type { PageChunkFilesMap } from '@vuepress/bundlerutils'
+import { resolveLinkRoutePath } from '@vuepress/bundlerutils'
+import type { App, Page } from '@vuepress/core'
 import type { OutputChunk } from 'rolldown'
 
 /**
@@ -8,10 +10,14 @@ export const renderPagePrefetchLinks = ({
   app,
   outputEntryChunk,
   pageChunkFiles,
+  page,
+  pageChunkFilesMap,
 }: {
   app: App
   outputEntryChunk: OutputChunk
   pageChunkFiles: string[]
+  page: Page
+  pageChunkFilesMap: PageChunkFilesMap
 }): string => {
   // shouldPrefetch option
   const { shouldPrefetch } = app.options
@@ -21,12 +27,37 @@ export const renderPagePrefetchLinks = ({
     return ''
   }
 
-  // dynamic imports excluding current page chunks
-  const prefetchFiles = outputEntryChunk.dynamicImports.filter(
-    (item) => !pageChunkFiles.some((file) => file === item),
-  )
+  let candidateFiles: string[]
 
-  return prefetchFiles
+  if (shouldPrefetch === 'as-needed') {
+    // collect linked page chunk file names
+    const linkedFileNames = new Set<string>()
+    for (const link of page.links) {
+      const routePath = resolveLinkRoutePath(link.absolute, app.options.base)
+      if (routePath) {
+        const targetChunks = pageChunkFilesMap.get(routePath)
+        if (targetChunks) {
+          for (const file of targetChunks) {
+            linkedFileNames.add(file)
+          }
+        }
+      }
+    }
+    // dynamic imports excluding current page chunks
+    // filtered to only linked pages' chunk files
+    candidateFiles = outputEntryChunk.dynamicImports.filter(
+      (item) =>
+        linkedFileNames.has(item) &&
+        !pageChunkFiles.some((file) => file === item),
+    )
+  } else {
+    // dynamic imports excluding current page chunks
+    candidateFiles = outputEntryChunk.dynamicImports.filter(
+      (item) => !pageChunkFiles.some((file) => file === item),
+    )
+  }
+
+  return candidateFiles
     .map((item) => {
       // resolve file type
       const type = item.endsWith('.js')
@@ -36,7 +67,11 @@ export const renderPagePrefetchLinks = ({
           : ''
 
       // user wants to explicitly control what to prefetch
-      if (shouldPrefetch !== true && !shouldPrefetch(item, type)) {
+      if (
+        shouldPrefetch !== true &&
+        shouldPrefetch !== 'as-needed' &&
+        !shouldPrefetch(item, type)
+      ) {
         return ''
       }
       return `<link rel="prefetch" href="${app.options.base}${item}" as="${type}">`

packages/bundler-vite/src/build/renderPagePreloadLinks.ts

@@ -1,4 +1,6 @@
-import type { App } from '@vuepress/core'
+import type { PageChunkFilesMap } from '@vuepress/bundlerutils'
+import { resolveLinkRoutePath } from '@vuepress/bundlerutils'
+import type { App, Page } from '@vuepress/core'
 import type { OutputChunk } from 'rolldown'
 
 /**
@@ -8,10 +10,14 @@ export const renderPagePreloadLinks = ({
   app,
   outputEntryChunk,
   pageChunkFiles,
+  page,
+  pageChunkFilesMap,
 }: {
   app: App
   outputEntryChunk: OutputChunk
   pageChunkFiles: string[]
+  page: Page
+  pageChunkFilesMap: PageChunkFilesMap
 }): string => {
   // shouldPreload option
   const { shouldPreload } = app.options
@@ -30,6 +36,23 @@ export const renderPagePreloadLinks = ({
     ]),
   )
 
+  // when 'as-needed', also add linked pages' chunk files
+  if (shouldPreload === 'as-needed') {
+    for (const link of page.links) {
+      const routePath = resolveLinkRoutePath(link.absolute, app.options.base)
+      if (routePath) {
+        const targetChunks = pageChunkFilesMap.get(routePath)
+        if (targetChunks) {
+          for (const file of targetChunks) {
+            if (!preloadFiles.includes(file)) {
+              preloadFiles.push(file)
+            }
+          }
+        }
+      }
+    }
+  }
+
   return preloadFiles
     .map((item) => {
       // resolve file type
@@ -45,7 +68,11 @@ export const renderPagePreloadLinks = ({
       }
 
       // user wants to explicitly control what to preload
-      if (shouldPreload !== true && !shouldPreload(item, type)) {
+      if (
+        shouldPreload !== true &&
+        shouldPreload !== 'as-needed' &&
+        !shouldPreload(item, type)
+      ) {
         return ''
       }
 

packages/bundler-webpack/src/build/build.ts

@@ -1,3 +1,4 @@
+import type { PageChunkFilesMap } from '@vuepress/bundlerutils'
 import { createVueServerApp, getSsrTemplate } from '@vuepress/bundlerutils'
 import type { App, Bundler } from '@vuepress/core'
 import { colors, debug, fs, logger, withSpinner } from '@vuepress/utils'
@@ -78,6 +79,16 @@ export const build = async (
     const { initialFilesMeta, asyncFilesMeta, moduleFilesMetaMap } =
       resolveClientManifestMeta(clientManifest)
 
+    // build page path -> chunk files map for preload & prefetch
+    const pageChunkFilesMap: PageChunkFilesMap = new Map()
+    for (const page of app.pages) {
+      const pageFileNames = clientManifest.chunks[page.chunkName] ?? []
+
+      if (pageFileNames.length) {
+        pageChunkFilesMap.set(page.path, pageFileNames)
+      }
+    }
+
     // create vue ssr app and get ssr template
     const { vueApp, vueRouter } = await createVueServerApp(
       app.dir.temp('.server/app.cjs'),
@@ -98,6 +109,7 @@ export const build = async (
         initialFilesMeta,
         asyncFilesMeta,
         moduleFilesMetaMap,
+        pageChunkFilesMap,
       })
     }
   })

packages/bundler-webpack/src/build/createClientPlugin.ts

@@ -90,12 +90,23 @@ export const createClientPlugin = (
             if (request) manifestModules[request] = files
           })
 
+          // build chunk name -> file names mapping
+          const chunkFiles: Record<string, string[]> = {}
+          chunks.forEach((chunk) => {
+            if (chunk.names.length && chunk.files.length) {
+              chunk.names.forEach((name) => {
+                chunkFiles[name] = [...(chunkFiles[name] ?? []), ...chunk.files]
+              })
+            }
+          })
+
           // generate client manifest json file
           const clientManifest: ClientManifest = {
             all: allFiles,
             initial: initialFiles,
             async: asyncFiles,
             modules: manifestModules,
+            chunks: chunkFiles,
           }
 
           const clientManifestJson = JSON.stringify(clientManifest, null, 2)

packages/bundler-webpack/src/build/renderPage.ts

@@ -1,4 +1,4 @@
-import type { PageSSRContext } from '@vuepress/bundlerutils'
+import type { PageChunkFilesMap, PageSSRContext } from '@vuepress/bundlerutils'
 import { renderPageToString } from '@vuepress/bundlerutils'
 import type { App, Page } from '@vuepress/core'
 import { fs, renderHead } from '@vuepress/utils'
@@ -33,6 +33,7 @@ export const renderPage = async ({
   initialFilesMeta,
   asyncFilesMeta,
   moduleFilesMetaMap,
+  pageChunkFilesMap,
 }: {
   app: App
   page: Page
@@ -42,6 +43,7 @@ export const renderPage = async ({
   initialFilesMeta: FileMeta[]
   asyncFilesMeta: FileMeta[]
   moduleFilesMetaMap: ModuleFilesMetaMap
+  pageChunkFilesMap: PageChunkFilesMap
 }): Promise<void> => {
   // render current page to string
   const { ssrContext, ssrString } =
@@ -67,11 +69,15 @@ export const renderPage = async ({
       app,
       asyncFilesMeta,
       pageClientFilesMeta,
+      page,
+      pageChunkFilesMap,
     }),
     preload: renderPagePreloadLinks({
       app,
       initialFilesMeta,
       pageClientFilesMeta,
+      page,
+      pageChunkFilesMap,
     }),
     scripts: renderPageScripts({ app, initialFilesMeta, pageClientFilesMeta }),
     styles: renderPageStyles({ app, initialFilesMeta, pageClientFilesMeta }),

packages/bundler-webpack/src/build/renderPagePrefetchLinks.ts

@@ -1,4 +1,6 @@
-import type { App } from '@vuepress/core'
+import type { PageChunkFilesMap } from '@vuepress/bundlerutils'
+import { resolveLinkRoutePath } from '@vuepress/bundlerutils'
+import type { App, Page } from '@vuepress/core'
 
 import type { FileMeta } from './types.js'
 
@@ -9,10 +11,14 @@ export const renderPagePrefetchLinks = ({
   app,
   asyncFilesMeta,
   pageClientFilesMeta,
+  page,
+  pageChunkFilesMap,
 }: {
   app: App
   asyncFilesMeta: FileMeta[]
   pageClientFilesMeta: FileMeta[]
+  page: Page
+  pageChunkFilesMap: PageChunkFilesMap
 }): string => {
   // shouldPrefetch option
   const { shouldPrefetch } = app.options
@@ -22,15 +28,44 @@ export const renderPagePrefetchLinks = ({
     return ''
   }
 
-  // async files excluding files used by current page should be prefetch
-  const prefetchFilesMeta = asyncFilesMeta.filter(
-    ({ file }) => !pageClientFilesMeta.some((f) => f.file === file),
-  )
+  let prefetchFilesMeta: FileMeta[]
+
+  if (shouldPrefetch === 'as-needed') {
+    // collect linked page chunk file names
+    const linkedFileNames = new Set<string>()
+    for (const link of page.links) {
+      const routePath = resolveLinkRoutePath(link.absolute, app.options.base)
+      if (routePath) {
+        const targetChunks = pageChunkFilesMap.get(routePath)
+        if (targetChunks) {
+          for (const file of targetChunks) {
+            linkedFileNames.add(file)
+          }
+        }
+      }
+    }
+    // async files excluding files used by current page
+    // filtered to only linked pages' chunk files
+    prefetchFilesMeta = asyncFilesMeta.filter(
+      ({ file }) =>
+        linkedFileNames.has(file) &&
+        !pageClientFilesMeta.some((f) => f.file === file),
+    )
+  } else {
+    // async files excluding files used by current page should be prefetch
+    prefetchFilesMeta = asyncFilesMeta.filter(
+      ({ file }) => !pageClientFilesMeta.some((f) => f.file === file),
+    )
+  }
 
   return prefetchFilesMeta
     .map(({ file, type }) => {
       // user wants to explicitly control what to prefetch
-      if (shouldPrefetch !== true && !shouldPrefetch(file, type)) {
+      if (
+        shouldPrefetch !== true &&
+        shouldPrefetch !== 'as-needed' &&
+        !shouldPrefetch(file, type)
+      ) {
         return ''
       }
       return `<link rel="prefetch" href="${app.options.base}${file}" as="${type}">`