vite-plugin-preload

0.7.0 verified Mon Apr 27 auth: no javascript

Vite plugin that preloads all JS chunks and CSS stylesheets generated by dynamic imports (e.g., React.lazy) into the HTML entry point. As of v0.7.0, it automatically injects <link rel="modulepreload"> and <link rel="stylesheet"> tags for every chunk produced by code splitting, improving load performance by prefetching before the user navigates. It differs from manual chunking plugins by targeting framework-level lazy imports rather than Rollup's manualChunks. Released at a moderate cadence, it supports Vite 5+, TypeScript types out of the box, and offers options to filter chunks, choose preload vs prefetch mode, and generate a manifest JSON.

Common errors

error Error: Cannot find module 'vite-plugin-preload' ↓

cause Package not installed or peer dependency Vite version mismatch.

fix

Install the package: npm install -D vite-plugin-preload. Ensure Vite >=5.0.0 is installed.

error TypeError: preload is not a function ↓

cause Using named import instead of default import.

fix

Use default import: import preload from 'vite-plugin-preload'. Or in CJS: const preload = require('vite-plugin-preload').

error The option 'includeJs' is not recognized ↓

cause Using an outdated version of the plugin before includeJs was introduced.

fix

Upgrade to v0.7.0 or later: npm install vite-plugin-preload@latest. Check docs for options per version.

error Module parse failed: Unexpected token ↓

cause The plugin is not installed as a dev dependency or is being processed by a non-Vite build tool.

fix

Only use this plugin in a Vite project. It must be placed in the Vite config's plugins array.

Warnings

gotcha Plugin only processes chunks generated by dynamic imports (e.g., React.lazy), not manualChunks in Rollup. If you use manualChunks, the plugin will not add preload links for those chunks. ↓

fix Use dynamic imports for code splitting instead of manualChunks. Or consider using Vite's built-in manualChunks preloading.

gotcha When mode is 'prefetch', links use rel="prefetch" instead of rel="modulepreload". Be aware that prefetch has lower priority and browser support differences. ↓

fix If you need immediate preloading, set mode to 'preload' (default).

gotcha The `format` option applies Prettier formatting to the HTML output. It can cause unexpected line breaks or formatting if you have custom HTML template. ↓

fix Set format to false or provide a PrettierOptions object to control formatting.

gotcha The `shouldPreload` filter function receives chunk info; if not provided, all chunks are preloaded. Incorrect filter may exclude critical chunks. ↓

fix Implement a proper filter function that returns true for chunks you want to preload, e.g., (chunk) => chunk.fileName.endsWith('.js') && chunk.isDynamicEntry.

gotcha If you use Vite's `build.manifest` option, the generated manifest may not include the preload links added by this plugin. Use `generatePreloadManifestJsonPath` to output a separate manifest. ↓

fix Set `generatePreloadManifestJsonPath` to a file path to produce a JSON manifest of all preload links.

Install

npm install vite-plugin-preload

yarn add vite-plugin-preload

pnpm add vite-plugin-preload

Imports

default
wrong
```
const { preload } = require('vite-plugin-preload')
```
correct
```
import preload from 'vite-plugin-preload'
```
Default import only; named import 'preload' will be undefined. CJS require works via default export.
PreloadOptions
wrong
```
import { PreloadOptions } from 'vite-plugin-preload'
```
correct
```
import type { PreloadOptions } from 'vite-plugin-preload'
```
TypeScript users should use `import type` for type-only imports to avoid runtime side effects.
CommonJS require
```
const preload = require('vite-plugin-preload')
```
CJS users: the default export is the function; no destructuring needed.

Quickstart

Demonstrates the minimum Vite config to enable preloading of all dynamically-loaded JS chunks and CSS.

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import preload from 'vite-plugin-preload';

export default defineConfig({
  plugins: [
    react(),
    preload({
      includeJs: true,
      includeCss: true,
      mode: 'preload',
    }),
  ],
});