vite-plugin-ssr-hot-reload

0.5.0 verified Mon Apr 27 auth: no javascript

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.

Common errors

error ERR_HTTP_HEADERS_SENT ↓

cause Plugin modified headers after response already sent, commonly when using both injectViteClient and custom middleware.

fix

Update to v0.3.3+ which fixes this; ensure you are not calling response methods after plugin injection.

error Cannot find module 'vite-plugin-ssr-hot-reload' ↓

cause Package is ESM-only and cannot be required with CommonJS require().

fix

Use import instead of require, and ensure your project uses ESM (package.json type: module) or use dynamic import.

error [vite] Internal server error: ... is not a function ↓

cause Imported the module incorrectly, likely using named import instead of default import.

fix

Use default import: import ssrHotReload from 'vite-plugin-ssr-hot-reload'

error Error: The injectReactRefresh option requires @vitejs/plugin-react to be installed ↓

cause Attempted to use injectReactRefresh without installing @vitejs/plugin-react.

fix

Install @vitejs/plugin-react (npm install -D @vitejs/plugin-react) and add react() to Vite plugins.

Warnings

gotcha Option `injectReactRefresh` requires `@vitejs/plugin-react` to be installed and used in the Vite config. Without it, the injected scripts will not function. ↓

fix Install @vitejs/plugin-react and add react() plugin before ssrHotReload.

breaking In v0.4.0, the plugin changed the position of the React refresh script injection to the end of <head>. If your HTML parsing relies on script order, this may break expectations. ↓

fix Ensure your HTML head can accept scripts at the end; no code change needed.

gotcha Node version requirement >=18.0.0. Using older Node will cause runtime errors. ↓

fix Upgrade Node to version 18 or higher.

deprecated The `modules` parameter in handleHotUpdate was deprecated in v0.2.2; use `file` instead. ↓

fix Update to version >=0.3.0 which handles this internally. No user action needed.

gotcha 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. ↓

fix Update to version >=0.3.2 or avoid leading slashes in paths.

Install

npm install vite-plugin-ssr-hot-reload

yarn add vite-plugin-ssr-hot-reload

pnpm add vite-plugin-ssr-hot-reload

Imports

ssrHotReload

wrong

const ssrHotReload = require('vite-plugin-ssr-hot-reload')

correct

import ssrHotReload from 'vite-plugin-ssr-hot-reload'

ESM-only; CommonJS require not supported.

ssrHotReload (default import)

wrong

import { ssrHotReload } from 'vite-plugin-ssr-hot-reload'

correct

import ssrHotReload from 'vite-plugin-ssr-hot-reload'

Package only exports a default export; named import will fail.

VitePluginSsrHotReload (type import)

wrong

import { VitePluginSsrHotReload } from 'vite-plugin-ssr-hot-reload'

correct

import type { VitePluginSsrHotReload } from 'vite-plugin-ssr-hot-reload'

Type-only import for TypeScript users; runtime usage will cause error.

Quickstart

Shows usage with entry, ignore, and injectReactRefresh options in Vite config.

// vite.config.ts
import { defineConfig } from 'vite'
import ssrHotReload from 'vite-plugin-ssr-hot-reload'

export default defineConfig({
  plugins: [
    ssrHotReload({
      entry: ['/src/pages/**/*.tsx', '/src/layouts/**/*.ts'],
      ignore: ['/src/pages/ignored/**/*.tsx'],
      injectReactRefresh: true
    })
  ]
})