{"record":{"id":"3846b1354f7c286d","repo":"remix-run/remix","slug":"nodehmrruntimeunavailableerror","errorCode":null,"errorMessage":"nodeHmrRuntimeUnavailableError","messagePattern":"nodeHmrRuntimeUnavailableError","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/node-hmr/src/runtime.node-hmr.ts","lineNumber":9,"sourceCode":"import { emitServerReady, getNodeHmrRuntime } from './lib/runtime.ts'\nimport type { NodeHmrRuntimeApi } from './lib/runtime-api.ts'\nimport { nodeHmrRuntimeUnavailableError } from './lib/runtime-api.ts'\n\nexport type { BrowserHmrChannel } from './lib/browser-events.ts'\n\nconst maybeNodeHmrRuntime = getNodeHmrRuntime()\nif (maybeNodeHmrRuntime === undefined) {\n  throw new Error(nodeHmrRuntimeUnavailableError)\n}\nconst nodeHmrRuntime = maybeNodeHmrRuntime\n\n/**\n * Connects browser asset tooling in this child process to the browser HMR event stream and file\n * watcher owned by its `node-hmr` parent process.\n *\n * Pass this function as the `hmr` factory for `createAssetServer()`. Each call creates an\n * independent channel that must be closed when its owner shuts down. The returned promise rejects\n * when browser HMR is disabled for the runner.\n *\n * The `remix/node-hmr/runtime` module itself can only be imported by a process supervised by\n * `node-hmr`. Use a dynamic import guarded by `process.env.REMIX_NODE_HMR` when the same entry module\n * also runs without HMR supervision.\n *\n * @returns A child-scoped channel for watching browser source files and publishing HMR events.\n */\nexport const createBrowserHmrChannel: NodeHmrRuntimeApi['createBrowserHmrChannel'] =","sourceCodeStart":1,"sourceCodeEnd":27,"githubUrl":"https://github.com/remix-run/remix/blob/9696913134be3a4423513d2775f7b31d6917c049/packages/node-hmr/src/runtime.node-hmr.ts#L1-L27","documentation":"Importing node-hmr/runtime.node-hmr.ts immediately checks for the node-hmr runtime via globalThis; if absent it throws Error('The node-hmr/runtime API is only available when running inside node-hmr'). The module is designed to run only in child processes spawned by the node-hmr supervisor, so importing it elsewhere fails at import time.","triggerScenarios":"import-ing 'node-hmr/runtime' (runtime.node-hmr.ts) in a process not launched under node-hmr — plain node scripts, tests, or servers started without the node-hmr CLI — so getNodeHmrRuntime() returns undefined.","commonSituations":"Build/test tooling that transitively bundles or imports the runtime module outside dev; running the dev server with node instead of node-hmr; version changes making the module eager where it was lazy before.","solutions":["Only import node-hmr/runtime from code that runs under the node-hmr supervisor (e.g. via register hooks it installs)","Guard the import with await import() inside a check for the runtime global, so standalone execution can skip it","Start your dev process with the node-hmr CLI entrypoint"],"exampleFix":"// before\nimport { createBrowserHmrChannel } from 'node-hmr/runtime' // throws at import outside node-hmr\n\n// after\nlet nodeHmr = globalThis.__nodeHmrRuntime__\nif (nodeHmr) {\n  let { createBrowserHmrChannel } = await import('node-hmr/runtime')\n  await createBrowserHmrChannel()\n}","handlingStrategy":"fallback","validationCode":"if (typeof globalThis !== 'undefined' && '__nodeHmrRuntime' in globalThis) {\n  const runtime = await import('node-hmr/runtime')\n  await runtime.createBrowserHmrChannel()\n}","typeGuard":"const isNodeHmrChild = (): boolean =>\n  typeof globalThis === 'object' && globalThis !== null && '__nodeHmrRuntime' in globalThis","tryCatchPattern":"try {\n  await import('node-hmr/runtime')\n} catch (error) {\n  if (error instanceof Error && error.message.includes('only available when running inside node-hmr')) {\n    // standalone execution — skip node-hmr features\n  } else throw error\n}","preventionTips":["Import node-hmr/runtime dynamically, only after confirming the runtime global exists","Run dev servers through the node-hmr CLI entrypoint","Keep node-hmr imports out of test/build bundles"],"tags":["node-hmr","import-time-error","runtime-unavailable"],"backgroundTag":"hmr-runtime-unavailable","analyzedSha":"9696913134be3a4423513d2775f7b31d6917c049","analyzedAt":"2026-08-27T19:55:01.024Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}