{"id":22559,"library":"vite-hot-client","title":"vite-hot-client","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/antfu/vite-hot-client","tags":["javascript","typescript"],"install":[{"cmd":"npm install vite-hot-client","lang":"bash","label":"npm"},{"cmd":"yarn add vite-hot-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-hot-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; uses Vite's HMR internals.","package":"vite","optional":false}],"imports":[{"note":"ESM-only since v2; require() will throw.","wrong":"const { hot } = require('vite-hot-client')","symbol":"hot","correct":"import { hot } from 'vite-hot-client'"},{"symbol":"createHotContext","correct":"import { createHotContext } from 'vite-hot-client'"},{"note":"Introduced in v0.2.0; older versions only have createHotContext.","symbol":"tryCreateHotContext","correct":"import { tryCreateHotContext } from 'vite-hot-client'"}],"quickstart":{"code":"import { hot, createHotContext } from 'vite-hot-client'\n\n// 1) Use pre-exported 'hot' (works when module has import.meta.hot)\nif (hot) {\n  console.log('HMR connected')\n  hot.on('vite:beforeFullReload', () => console.log('reloading'))\n}\n\n// 2) Create context for a virtual module path (e.g., for custom UI)\nconst ctx = createHotContext('/@my-plugin/client')\nif (ctx) {\n  ctx.send('custom:update', { data: 'hello' })\n}","lang":"typescript","description":"Shows using the 'hot' export and createHotContext() for custom HMR communication."},"warnings":[{"fix":"Use ES module imports (import { hot } from 'vite-hot-client'); remove any require() calls.","message":"v2.0.0 adopted Epoch SemVer; previous version was v0.x. Imports unchanged but package is now ESM-only.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace hot.on(...) with createHotContext('/path/to/module').on(...) or use the exported 'hot' (which is pre-bound to the current module).","message":"v0.2.0 removed the anonymous hot context (hot without arguments). Must use createHotContext(path) or tryCreateHotContext() instead.","severity":"breaking","affected_versions":">=0.2.0 <0.2.0"},{"fix":"Use tryCreateHotContext to safely create a context, which returns null instead of throwing.","message":"tryCreateHotContext was added in v0.2.0; older createHotContext may throw if Vite is not available.","severity":"deprecated","affected_versions":"<0.2.0"},{"fix":"Guard usage with process.env.NODE_ENV !== 'production' or similar.","message":"The package does not work in production builds; it's only for development (Vite dev server).","severity":"gotcha","affected_versions":"*"},{"fix":"Check if hot is truthy before using: if (hot) { ... }","message":"import.meta.hot may be undefined in some environments (e.g., SSR, tests). Always check hot or the returned context for null.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Set 'type': 'module' in package.json or use .mjs extension.","cause":"Using import in a CommonJS file or Node.js without 'type: module'.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Ensure vite-hot-client is symlinked or installed correctly; it is ESM-only since v2. Use dynamic import() if necessary.","cause":"Using named import from a CommonJS build of vite-hot-client.","error":"The requested module 'vite-hot-client' does not provide an export named 'hot'"},{"fix":"Access 'hot' inside a function or after the module is loaded; it's set synchronously when import.meta.hot is available.","cause":"Accessing the exported 'hot' before it's assigned (e.g., in top-level code during module evaluation).","error":"ReferenceError: hot is not defined"},{"fix":"Check for null: const ctx = createHotContext(...); if (ctx) { ctx.on(...) }","cause":"createHotContext or hot returns null when Vite HMR is not available, but code attempts to call methods on null.","error":"TypeError: Cannot read properties of null (reading 'on')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}