{"id":22940,"library":"vite-preload","title":"vite-preload","description":"Vite plugin (v1.0.6) that preloads server-rendered lazy React components and their CSS to eliminate FOUC and reduce load times. Unlike vite-plugin-preload, it evaluates used modules at render time (not build time). Supports Vite 5-8 and React 18-19. Ships TypeScript types, offers lazy() wrapper and preloadAll() for server-side resolution. Compatible with 103 Early Hints via getLinkHeaders(). Active development with frequent releases.","status":"active","version":"1.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/wille/vite-preload","tags":["javascript","react","css","ssr","esmodules","vite","vite-plugin","typescript"],"install":[{"cmd":"npm install vite-preload","lang":"bash","label":"npm"},{"cmd":"yarn add vite-preload","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-preload","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Lazy component preloading and context API depend on React","package":"react","optional":false},{"reason":"Required as a Vite plugin","package":"vite","optional":false}],"imports":[{"note":"Default export from 'vite-preload/plugin' subpath; named import will not work.","wrong":"import { preloadPlugin } from 'vite-preload/plugin'","symbol":"preloadPlugin","correct":"import preloadPlugin from 'vite-preload/plugin'"},{"note":"ESM-only; named import from main path. CJS require may fail in some environments.","wrong":"const createChunkCollector = require('vite-preload').createChunkCollector","symbol":"createChunkCollector","correct":"import { createChunkCollector } from 'vite-preload'"},{"note":"Named export, not default. Wraps server render to collect chunks.","wrong":"import ChunkCollectorContext from 'vite-preload'","symbol":"ChunkCollectorContext","correct":"import { ChunkCollectorContext } from 'vite-preload'"},{"note":"Client-side/server-side helper from main entry, not from plugin subpath.","wrong":"import { preloadAll } from 'vite-preload/plugin'","symbol":"preloadAll","correct":"import { preloadAll } from 'vite-preload'"},{"note":"This is a React.lazy wrapper with preload detection; replaces React.lazy usage.","wrong":"import { lazy } from 'react'","symbol":"lazy","correct":"import { lazy } from 'vite-preload'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport preloadPlugin from 'vite-preload/plugin';\n\nexport default defineConfig({\n  plugins: [\n    preloadPlugin(),\n    react()\n  ]\n});\n\n// server/entry.server.tsx (simplified)\nimport { ChunkCollectorContext, createChunkCollector, preloadAll } from 'vite-preload';\nimport React from 'react';\nimport { renderToPipeableNodeStream } from 'react-dom/server';\n\n// On server startup:\nawait preloadAll();\n\n// In request handler:\nconst collector = createChunkCollector({\n  manifest: './dist/client/.vite/manifest.json',\n  entry: 'index.html'\n});\n\n// Early Hints\nres.writeEarlyHints({ link: collector.getLinkHeaders() });\n\nconst { pipe } = renderToPipeableNodeStream(\n  <ChunkCollectorContext.Provider value={collector}>\n    <App />\n  </ChunkCollectorContext.Provider>\n);\n\n// After rendering, inject <link> tags into HTML head\nconst linkTags = collector.getLinkTags();\nconst html = template.replace('</head>', `${linkTags}</head>`);\nres.write(html);\n","lang":"typescript","description":"Shows Vite plugin setup, server-side chunk collector initialization, Early Hints, and link tag injection."},"warnings":[{"fix":"Only rely on preloading for production builds; test CSS appearance separately in dev.","message":"Preloading does not work in development mode (vite dev). CSS is injected via inline style tags causing FOUC.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Remove experimentalMinChunkSize or set it to 0.","message":"If modules are not preloaded, check that build.rollupOptions.output.experimentalMinChunkSize is not set, as Rollup may merge chunks and break manifest mapping.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Use import syntax or enable ESM in Node.js (\"type\": \"module\" in package.json).","message":"CJS require() may fail in some environments. Package is ESM-only.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade React to version 18 or later.","message":"React 17 is not supported as a peer dependency; only React 18 and 19 are allowed.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Ensure you do not hydrate or render React before DOMContentLoaded if using asyncScript.","message":"The 'asyncScript' option generates async entry module; React hydration must wait for DOMContentLoaded.","severity":"gotcha","affected_versions":">=1.0.3"},{"fix":"Use import preloadPlugin from 'vite-preload/plugin'.","message":"The plugin import path changed: import from 'vite-preload/plugin', not 'vite-preload'.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use default import from 'vite-preload/plugin': import preloadPlugin from 'vite-preload/plugin'.","cause":"Importing preloadPlugin from wrong path (e.g., import { preloadPlugin } from 'vite-preload').","error":"Error: The 'vite-preload' plugin is not found or not configured correctly."},{"fix":"Ensure manifest path points to valid file (e.g., './dist/client/.vite/manifest.json') and file exists.","cause":"createChunkCollector returned undefined because manifest path is incorrect or file not found.","error":"TypeError: Cannot read properties of undefined (reading 'getLinkHeaders')"},{"fix":"Remove build.rollupOptions.output.experimentalMinChunkSize or set to 0.","cause":"A lazy-loaded module's chunk is missing from the manifest; possibly due to Rollup chunk merging.","error":"[vite-preload] Chunk not found in manifest: ..."},{"fix":"Replace React.lazy with import { lazy } from 'vite-preload'.","cause":"Using React.lazy directly instead of the wrapper from 'vite-preload' which collects chunks.","error":"Error: React.lazy is not supported without the 'lazy' wrapper from vite-preload"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}