Registry / web-framework / vite-plugin-ssr-hot-reload

vite-plugin-ssr-hot-reload

library0.5.0jsnpmunverified

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.

web-framework

npm install vite-plugin-ssr-hot-reload

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-SSR-HO

vite-plugin-ssr-hot-reload

web-frameworkjavascriptv0.5.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.

ssrHotReload

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

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

ESM-only; CommonJS require not supported.

ssrHotReload (default import)

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

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

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

VitePluginSsrHotReload (type import)

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

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

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

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 }) ] })

Debug

Known issues

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

affects: >=0.4.0

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

affects: >=0.4.0

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

fix

Upgrade Node to version 18 or higher.

affects: >=0.5.0

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

affects: >=0.2.2,<0.3.0

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

affects: <0.3.2

Errors

Common errors & fixes

ERR_HTTP_HEADERS_SENT

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.

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

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.

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

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: The injectReactRefresh option requires @vitejs/plugin-react to be installed

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.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

@vitejs/plugin-reactoptionalOnly needed if using injectReactRefresh option

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/yusukebe/vite-plugin-ssr-hot-reload ↗

packagehttps://www.npmjs.com/package/vite-plugin-ssr-hot-reload ↗