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
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
preloadPlugin
✓ import preloadPlugin from 'vite-preload/plugin'
✗ import { preloadPlugin } from 'vite-preload/plugin'
Default export from 'vite-preload/plugin' subpath; named import will not work.
createChunkCollector
✓ import { createChunkCollector } from 'vite-preload'
✗ const createChunkCollector = require('vite-preload').createChunkCollector
ESM-only; named import from main path. CJS require may fail in some environments.
ChunkCollectorContext
✓ import { ChunkCollectorContext } from 'vite-preload'
✗ import ChunkCollectorContext from 'vite-preload'
Named export, not default. Wraps server render to collect chunks.
preloadAll
✓ import { preloadAll } from 'vite-preload'
✗ import { preloadAll } from 'vite-preload/plugin'
Client-side/server-side helper from main entry, not from plugin subpath.
lazy
✓ import { lazy } from 'vite-preload'
✗ import { lazy } from 'react'
This is a React.lazy wrapper with preload detection; replaces React.lazy usage.
Shows Vite plugin setup, server-side chunk collector initialization, Early Hints, and link tag injection.
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import preloadPlugin from 'vite-preload/plugin';
export default defineConfig({
plugins: [
preloadPlugin(),
react()
]
});
// server/entry.server.tsx (simplified)
import { ChunkCollectorContext, createChunkCollector, preloadAll } from 'vite-preload';
import React from 'react';
import { renderToPipeableNodeStream } from 'react-dom/server';
// On server startup:
await preloadAll();
// In request handler:
const collector = createChunkCollector({
manifest: './dist/client/.vite/manifest.json',
entry: 'index.html'
});
// Early Hints
res.writeEarlyHints({ link: collector.getLinkHeaders() });
const { pipe } = renderToPipeableNodeStream(
<ChunkCollectorContext.Provider value={collector}>
<App />
</ChunkCollectorContext.Provider>
);
// After rendering, inject <link> tags into HTML head
const linkTags = collector.getLinkTags();
const html = template.replace('</head>', `${linkTags}</head>`);
res.write(html);
Errors
Common errors & fixes
Error: The 'vite-preload' plugin is not found or not configured correctly.
Importing preloadPlugin from wrong path (e.g., import { preloadPlugin } from 'vite-preload').
fixUse default import from 'vite-preload/plugin': import preloadPlugin from 'vite-preload/plugin'.
TypeError: Cannot read properties of undefined (reading 'getLinkHeaders')
createChunkCollector returned undefined because manifest path is incorrect or file not found.
fixEnsure manifest path points to valid file (e.g., './dist/client/.vite/manifest.json') and file exists.
[vite-preload] Chunk not found in manifest: ...
A lazy-loaded module's chunk is missing from the manifest; possibly due to Rollup chunk merging.
fixRemove build.rollupOptions.output.experimentalMinChunkSize or set to 0.
Error: React.lazy is not supported without the 'lazy' wrapper from vite-preload
Using React.lazy directly instead of the wrapper from 'vite-preload' which collects chunks.
fixReplace React.lazy with import { lazy } from 'vite-preload'. Audit
Dependencies
reactrequiredLazy component preloading and context API depend on React
viterequiredRequired as a Vite plugin