vue-hot-reload-api

vue-hot-reload-api is the tracking and instance-swapping engine behind Vue 2’s hot module replacement. It doesn’t hook into webpack or any bundler itself — instead it exposes a small set of functions (install, createRecord, rerender, reload) that a build tool calls at the right moments to keep every live instance of a component discoverable and safely swappable when its source changes.

It is not meant to be used directly in application code. vue-loader and vueify both depend on it under the hood so that editing a .vue file’s template, script, or render function during development updates running instances in place — preserving component state — instead of forcing a full page reload.

What You Get

• A tiny, dependency-free tracking layer that maps component ids to their live Vue instances via injected lifecycle hooks
• Separate rerender (template/render-only changes) and reload (full option changes) code paths, each tuned to preserve as much running state as possible
• Built-in compatibility guarding — install() checks the host Vue version and exposes a compatible flag so callers can bail out cleanly on unsupported versions
• Defensive error handling via a tryWrap wrapper that turns internal hot-reload failures into a console warning instead of a crash

Common Use Cases

• Powering webpack’s Hot Module Replacement inside vue-loader so editing a .vue file updates the browser instantly
• Backing vueify’s Browserify-based Vue build pipeline with the same hot-swap behavior
• Building a custom Vue build tool or bundler plugin that needs to hot-swap component options during development

Under The Hood

Architecture vue-hot-reload-api is a single-module library (all logic lives in src/index.js) built around one shared record map keyed by a caller-supplied component id; install(Vue) performs a one-time compatibility check against the host Vue version and detects the lifecycle hook name (init vs beforeCreate) needed for pre-2.0-alpha Vue builds, createRecord registers a component’s options/constructor and an empty instances array, and makeOptionsHot injects tracking hooks (an init/beforeCreate handler that pushes instances onto the record, and a beforeDestroy handler that removes them) so every live instance of a hot component stays discoverable. rerender and reload are both wrapped in a tryWrap helper that catches and logs errors so a broken hot-swap degrades to a console warning rather than crashing the host app; reload rebuilds the constructor via Vue’s extend() and forces a re-render on each instance’s parent, while rerender swaps render/staticRenderFns directly and, for Vue 2.6+, temporarily patches the internal scoped-slots resolver to force child updates. There are no internal layers or abstractions beyond this single map/record model — the entire architecture exists to answer one question for a webpack/HMR caller like vue-loader: which live Vue instances correspond to a given source file, and how do I swap their behavior in place. If the shared map or the hook-injection mechanism broke, hot reloading would silently stop tracking instances and fall back to full page reloads.

Tech Stack The package ships as a CommonJS module (main: dist/index.js) written in plain ES2015+ JavaScript with no runtime dependencies; the source in src/ is compiled to dist/ with buble (a lightweight ES2015-to-ES5 compiler, chosen over Babel for its smaller footprint) via the build script, and prepublishOnly re-runs both the test suite and the build before every npm publish. Vue itself (^2.5.21) is a devDependency only, used purely to exercise the test suite. There is no bundler, TypeScript, or application framework involved — the whole package is a single hand-written utility module intended to be pulled in by build tools (vue-loader, vueify) rather than end applications.

Code Quality Test coverage lives in a single test/test.js file (jest) exercising rerender and reload across mounted, unmounted, and functional-component scenarios, including instance-count assertions via created/destroyed hooks — a reasonable functional test suite for a module this size, though there is no visible CI configuration (no .github/workflows or .travis.yml) wiring those tests into pull requests. There is no TypeScript and no type declarations; the code relies on plain JS objects and duck-typing (checking typeof options === ‘function’ to distinguish a constructor from an options object). No ESLint or Prettier configuration is present in the repo, so style consistency depends on convention rather than tooling; naming is terse but consistent (options, record, instances), and error handling is deliberate rather than accidental — the tryWrap wrapper explicitly converts internal exceptions into console warnings so a hot-reload failure degrades gracefully instead of crashing the app.

API Design The public API is intentionally minimal — install, createRecord, isRecorded, rerender, reload — and the README is explicit that this is not meant for direct application use (‘you will only be using this if you are writing some build toolchain’), so ergonomics are optimized for a single caller archetype (a webpack loader) rather than general developers. Getting started requires no configuration beyond a single install(Vue) call, but correct usage depends on the caller managing unique ids and calling create/rerender/reload in the right order and at the right lifecycle moment — there’s no validation or descriptive error if a caller passes an unregistered id. Documentation is limited to the README’s single usage example plus inline JSDoc-style comments on each exported function; there’s no dedicated API reference or examples directory. For its narrow audience of build-tool authors the API is adequate and stable, but it offers little discoverability or guidance for anyone outside that use case.