{"id":22849,"library":"vite-plugin-ssr-hot-reload","title":"vite-plugin-ssr-hot-reload","description":"A Vite plugin that forces a full page reload when your SSR entry file changes and injects the Vite client script for HMR in SSR contexts. Current stable version is 0.5.0, released October 2024, with a release cadence of minor versions every few months. Key differentiators: lightweight, no external dependencies, supports React refresh injection, and customizable entry/ignore patterns. Requires Node >= 18.0.0 and Vite.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/yusukebe/vite-plugin-ssr-hot-reload","tags":["javascript"],"install":[{"cmd":"npm install vite-plugin-ssr-hot-reload","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-ssr-hot-reload","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-ssr-hot-reload","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Only needed if using injectReactRefresh option","package":"@vitejs/plugin-react","optional":true}],"imports":[{"note":"ESM-only; CommonJS require not supported.","wrong":"const ssrHotReload = require('vite-plugin-ssr-hot-reload')","symbol":"ssrHotReload","correct":"import ssrHotReload from 'vite-plugin-ssr-hot-reload'"},{"note":"Package only exports a default export; named import will fail.","wrong":"import { ssrHotReload } from 'vite-plugin-ssr-hot-reload'","symbol":"ssrHotReload (default import)","correct":"import ssrHotReload from 'vite-plugin-ssr-hot-reload'"},{"note":"Type-only import for TypeScript users; runtime usage will cause error.","wrong":"import { VitePluginSsrHotReload } from 'vite-plugin-ssr-hot-reload'","symbol":"VitePluginSsrHotReload (type import)","correct":"import type { VitePluginSsrHotReload } from 'vite-plugin-ssr-hot-reload'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite'\nimport ssrHotReload from 'vite-plugin-ssr-hot-reload'\n\nexport default defineConfig({\n plugins: [\n ssrHotReload({\n entry: ['/src/pages/**/*.tsx', '/src/layouts/**/*.ts'],\n ignore: ['/src/pages/ignored/**/*.tsx'],\n injectReactRefresh: true\n })\n ]\n})","lang":"typescript","description":"Shows usage with entry, ignore, and injectReactRefresh options in Vite config."},"warnings":[{"fix":"Install @vitejs/plugin-react and add react() plugin before ssrHotReload.","message":"Option `injectReactRefresh` requires `@vitejs/plugin-react` to be installed and used in the Vite config. Without it, the injected scripts will not function.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Ensure your HTML head can accept scripts at the end; no code change needed.","message":"In v0.4.0, the plugin changed the position of the React refresh script injection to the end of . If your HTML parsing relies on script order, this may break expectations.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Upgrade Node to version 18 or higher.","message":"Node version requirement >=18.0.0. Using older Node will cause runtime errors.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Update to version >=0.3.0 which handles this internally. No user action needed.","message":"The `modules` parameter in handleHotUpdate was deprecated in v0.2.2; use `file` instead.","severity":"deprecated","affected_versions":">=0.2.2,<0.3.0"},{"fix":"Update to version >=0.3.2 or avoid leading slashes in paths.","message":"Paths in `entry` and `ignore` must be relative to project root and normalized (no leading slash issues). In v0.3.2, leading slash paths are supported, but earlier versions may fail.","severity":"gotcha","affected_versions":"<0.3.2"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Update to v0.3.3+ which fixes this; ensure you are not calling response methods after plugin injection.","cause":"Plugin modified headers after response already sent, commonly when using both injectViteClient and custom middleware.","error":"ERR_HTTP_HEADERS_SENT"},{"fix":"Use import instead of require, and ensure your project uses ESM (package.json type: module) or use dynamic import.","cause":"Package is ESM-only and cannot be required with CommonJS require().","error":"Cannot find module 'vite-plugin-ssr-hot-reload'"},{"fix":"Use default import: import ssrHotReload from 'vite-plugin-ssr-hot-reload'","cause":"Imported the module incorrectly, likely using named import instead of default import.","error":"[vite] Internal server error: ... is not a function"},{"fix":"Install @vitejs/plugin-react (npm install -D @vitejs/plugin-react) and add react() to Vite plugins.","cause":"Attempted to use injectReactRefresh without installing @vitejs/plugin-react.","error":"Error: The injectReactRefresh option requires @vitejs/plugin-react to be installed"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}