Registry / web-framework / vite-plugin-preload

vite-plugin-preload

library0.7.0jsnpmunverified

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.

web-framework

npm install vite-plugin-preload

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-PRELOA

vite-plugin-preload

web-frameworkjavascriptv0.7.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import preload from 'vite-plugin-preload'

✗ const { preload } = require('vite-plugin-preload')

Default import only; named import 'preload' will be undefined. CJS require works via default export.

PreloadOptions

✓ import type { PreloadOptions } from 'vite-plugin-preload'

✗ import { 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.

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', }), ], });

Debug

Known issues

gotchaPlugin 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.

affects: >=0.1.0

gotchaWhen 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).

affects: >=0.4.0

gotchaThe `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.

affects: >=0.2.0

gotchaThe `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.

affects: >=0.3.0

gotchaIf 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.

affects: >=0.5.0

Errors

Common errors & fixes

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

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.

TypeError: preload is not a function

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').

The option 'includeJs' is not recognized

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.

Module parse failed: Unexpected token

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.

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

viterequiredPeer dependency; plugin only works with Vite >= 5.0.0 as it hooks into Vite's build pipeline.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jarlef/vite-plugin-preload ↗

packagehttps://www.npmjs.com/package/vite-plugin-preload ↗