vite-hot-client

2.1.0 verified Mon Apr 27 auth: no javascript

A lightweight utility (v2.1.0, actively maintained) that allows you to access Vite's HMR API (`import.meta.hot`) at runtime, even in contexts where `import.meta.hot` is not directly available (e.g., inside iframes, worker threads, or dynamically evaluated code). It provides `hot`, `createHotContext`, and `tryCreateHotContext` functions. Key differentiator: solves the problem of accessing Vite's HMR client from outside standard Vite-managed modules, enabling dev tools like `vite-plugin-inspect` to communicate with the dev server over HMR. Requires `vite` ^2.6.0 || ^3.0.0 || ^4.0.0 || ^5.0.0-0 || ^6.0.0-0 || ^7.0.0-0. Ships TypeScript definitions and is ESM-only since v2.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause Using import in a CommonJS file or Node.js without 'type: module'.

fix

Set 'type': 'module' in package.json or use .mjs extension.

error The requested module 'vite-hot-client' does not provide an export named 'hot' ↓

cause Using named import from a CommonJS build of vite-hot-client.

fix

Ensure vite-hot-client is symlinked or installed correctly; it is ESM-only since v2. Use dynamic import() if necessary.

error ReferenceError: hot is not defined ↓

cause Accessing the exported 'hot' before it's assigned (e.g., in top-level code during module evaluation).

fix

Access 'hot' inside a function or after the module is loaded; it's set synchronously when import.meta.hot is available.

error TypeError: Cannot read properties of null (reading 'on') ↓

cause createHotContext or hot returns null when Vite HMR is not available, but code attempts to call methods on null.

fix

Check for null: const ctx = createHotContext(...); if (ctx) { ctx.on(...) }

Warnings

breaking v2.0.0 adopted Epoch SemVer; previous version was v0.x. Imports unchanged but package is now ESM-only. ↓

fix Use ES module imports (import { hot } from 'vite-hot-client'); remove any require() calls.

breaking v0.2.0 removed the anonymous hot context (hot without arguments). Must use createHotContext(path) or tryCreateHotContext() instead. ↓

fix Replace hot.on(...) with createHotContext('/path/to/module').on(...) or use the exported 'hot' (which is pre-bound to the current module).

deprecated tryCreateHotContext was added in v0.2.0; older createHotContext may throw if Vite is not available. ↓

fix Use tryCreateHotContext to safely create a context, which returns null instead of throwing.

gotcha The package does not work in production builds; it's only for development (Vite dev server). ↓

fix Guard usage with process.env.NODE_ENV !== 'production' or similar.

gotcha import.meta.hot may be undefined in some environments (e.g., SSR, tests). Always check hot or the returned context for null. ↓

fix Check if hot is truthy before using: if (hot) { ... }

Install

npm install vite-hot-client

yarn add vite-hot-client

pnpm add vite-hot-client

Imports

hot

wrong

const { hot } = require('vite-hot-client')

correct

import { hot } from 'vite-hot-client'

ESM-only since v2; require() will throw.

createHotContext

import { createHotContext } from 'vite-hot-client'

tryCreateHotContext
```
import { tryCreateHotContext } from 'vite-hot-client'
```
Introduced in v0.2.0; older versions only have createHotContext.

Quickstart

Shows using the 'hot' export and createHotContext() for custom HMR communication.

import { hot, createHotContext } from 'vite-hot-client'

// 1) Use pre-exported 'hot' (works when module has import.meta.hot)
if (hot) {
  console.log('HMR connected')
  hot.on('vite:beforeFullReload', () => console.log('reloading'))
}

// 2) Create context for a virtual module path (e.g., for custom UI)
const ctx = createHotContext('/@my-plugin/client')
if (ctx) {
  ctx.send('custom:update', { data: 'hello' })
}