vite-plugin-bundle-prefetch

0.0.4 verified Mon Apr 27 auth: no javascript

Vite plugin that automatically adds <link rel="prefetch"> tags to HTML output for all JavaScript chunks bundled in Vite builds. Current version 0.0.4 (beta, infrequent releases). The plugin scans the output directory for bundles, filters map files and legacy builds, then injects prefetch links into the final index.html. It addresses a gap where Vite's built-in preload only handles initial page loads, not prefetching for later navigation. Differentiates from similar tools like vite-plugin-prefetch by being minimal and focused on bundle-based prefetching. Works only with Vite; no support for rollup standalone or custom SSR pipelines.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/vite-plugin-bundle-prefetch/dist/index.mjs from /path/to/vite.config.js not supported. ↓

cause CJS require() used on ESM-only package.

fix

Change vite.config.js extension to .mjs or add type: 'module' in package.json, then use import prefetchPlugin from 'vite-plugin-bundle-prefetch'

error TypeError: prefetchPlugin is not a function ↓

cause Importing the plugin incorrectly (e.g., using import { prefetchPlugin } or incorrect destructuring).

fix

Use default import: import prefetchPlugin from 'vite-plugin-bundle-prefetch' (no curly braces)

Warnings

gotcha Plugin only works during build (vite build), not dev server. Prefetch links will not appear in dev mode. ↓

fix Run vite build to see prefetch links in output HTML.

gotcha excludeFn default is undefined, meaning no files are excluded; all bundle files (including .map) may get prefetched if not filtered. ↓

fix Provide excludeFn to skip .map files and legacy builds: excludeFn: (name) => name.includes('.map') || name.includes('legacy')

gotcha Plugin does not deduplicate prefetch links; if multiple plugins or manual links exist, duplicates may appear. ↓

fix Manually ensure no other prefetch links are added, or use transformIndexHtml hook to deduplicate.

Install

npm install vite-plugin-bundle-prefetch

yarn add vite-plugin-bundle-prefetch

pnpm add vite-plugin-bundle-prefetch

Imports

prefetchPlugin

wrong

const prefetchPlugin = require('vite-plugin-bundle-prefetch')

correct

import prefetchPlugin from 'vite-plugin-bundle-prefetch'

Default export; ESM-only, CJS require will throw. Plugin is a function, not an object.

Options

wrong

import { Options } from 'vite-plugin-bundle-prefetch'

correct

import type { Options } from 'vite-plugin-bundle-prefetch'

Options type is a TypeScript type, imported as type only. Do not use runtime import.

UserConfig

wrong

import prefetchPlugin from 'vite-plugin-bundle-prefetch/prefetchPlugin'

correct

import { defineConfig, UserConfig } from 'vite'; 
// then use prefetchPlugin in plugins array

No subpath exports; always import from main package.

Quickstart

Minimal Vite config adding prefetch for all built JavaScript chunks, excluding source maps and legacy bundles.

// vite.config.ts
import { defineConfig } from 'vite';
import prefetchPlugin from 'vite-plugin-bundle-prefetch';

export default defineConfig({
  plugins: [
    prefetchPlugin({
      excludeFn: (assetName: string) => assetName.includes('.map') || assetName.includes('legacy'),
    }),
  ],
});
// Build with `vite build`; output HTML will have <link rel="prefetch" href="/assets/chunk-xxx.js"> for all chunks.