Registry / web-framework / vite-hot-client

vite-hot-client

library2.1.0jsnpmunverified

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.

web-framework http-networking

npm install vite-hot-client

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-HOT-CLIENT

vite-hot-client

web-frameworkjavascriptv2.1.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.

hot

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

✗ const { hot } = require('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.

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

Debug

Known issues

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

affects: >=2.0.0

breakingv0.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).

affects: >=0.2.0 <0.2.0

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

affects: <0.2.0

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

affects: *

gotchaimport.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) { ... }

affects: *

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

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

fix

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

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

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.

ReferenceError: hot is not defined

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.

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

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(...) }

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

viterequiredPeer dependency; uses Vite's HMR internals.

Agent activity

15 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/antfu/vite-hot-client ↗

packagehttps://www.npmjs.com/package/vite-hot-client ↗