Vue Hot Reload API

2.3.4 · maintenance · verified Sun Apr 19

vue-hot-reload-api is a foundational utility designed to provide the core API for hot module replacement (HMR) within Vue 2.x applications. It serves as an internal dependency for higher-level build tools like `vue-loader` and `vueify`, enabling developers to update Vue components in the browser without a full page reload, thereby preserving application state during development. The package's current stable version is 2.3.4, with releases primarily focusing on compatibility fixes for the Vue 2.x ecosystem. It is critically important to note that this package is strictly tied to Vue 2.x; it offers no support for Vue 3 or later versions, which have their own integrated HMR mechanisms. Therefore, its utility is confined to legacy Vue 2 projects. Application developers generally do not interact with this package directly but rather benefit from its functionality through their chosen build setup. Its release cadence is infrequent, reflecting its mature status within a specific, older framework version.

Common errors

```
vue-hot-reload-api is not compatible with the version of Vue you are using.
```
cause The installed Vue version is incompatible with `vue-hot-reload-api` (e.g., Vue 3.x is being used instead of Vue 2.x).

fix Ensure your project uses Vue 2.x. If migrating to Vue 3, this package is not needed as Vue 3 has its own HMR mechanisms.
```
TypeError: api.createRecord is not a function
```
cause `api.install(Vue)` was not called or Vue was not correctly passed, leading to the API not being properly initialized.

fix Verify that `api.install(Vue)` is called once at startup, passing the correct Vue constructor instance from your application.

Warnings

breaking This package is strictly compatible only with Vue 2.x. Attempting to use it with Vue 3 or later will result in runtime errors and unexpected behavior as Vue 3 has its own HMR mechanisms.
Fix: Ensure your project explicitly uses Vue 2.x if this package is required. For Vue 3, rely on its native HMR support without this package.
gotcha This API is designed for underlying build tool implementations (e.g., vue-loader) and is not intended for direct use by application developers. Directly integrating it into application code is generally discouraged.
Fix: For application development, rely on build tools like `vue-loader` which abstract this API. Only use directly if developing a custom Vue 2.x build solution.
gotcha Failure to call `api.install(Vue)` with your active Vue instance before using other API methods will lead to runtime errors or incorrect hot-reloading behavior, as the API needs to be initialized with the Vue constructor.
Fix: Always ensure `api.install(Vue)` is the first method called after requiring the module, passing the Vue constructor that your application is using.

Install

npm install vue-hot-reload-api npm
yarn add vue-hot-reload-api yarn
pnpm add vue-hot-reload-api pnpm

Imports

api
wrong:
```
import api from 'vue-hot-reload-api'
```
correct:
```
const api = require('vue-hot-reload-api')
```
The package is primarily CommonJS; direct ESM default import may not work without bundler configuration.
install
wrong:
```
import { install } from 'vue-hot-reload-api'
```
correct:
```
const { install } = require('vue-hot-reload-api')
```
For named methods, destructuring from the CommonJS require call is the correct approach.
createRecord
wrong:
```
import { createRecord } from 'vue-hot-reload-api'
```
correct:
```
const { createRecord } = require('vue-hot-reload-api')
```
Similar to 'install', use destructuring for other core functions like 'createRecord', 'rerender', and 'reload'.

Quickstart

Demonstrates how to initialize the hot-reload API, install it with Vue, and implement hot reloading for a component's template (rerender) or full options (reload) within a Webpack HMR context.

const myComponentOptions = {
  data () { return { msg: 'Hello' } },
  created () { console.log('Component created!') },
  render (h) { return h('div', this.msg) }
}

// assuming Webpack's HMR API.
// https://webpack.js.org/guides/hot-module-replacement/
if (module.hot) {
  const api = require('vue-hot-reload-api')
  const Vue = require('vue')

  // make the API aware of the Vue that you are using.
  // also checks compatibility.
  api.install(Vue)

  // compatibility can be checked via api.compatible after installation
  if (!api.compatible) {
    throw new Error('vue-hot-reload-api is not compatible with the version of Vue you are using.')
  }

  // indicate this module can be hot-reloaded
  module.hot.accept()

  if (!module.hot.data) {
    // for each component option object to be hot-reloaded,
    // you need to create a record for it with a unique id.
    // do this once on startup.
    api.createRecord('very-unique-id', myComponentOptions)
  } else {
    // if a component has only its template or render function changed,
    // you can force a re-render for all its active instances without
    // destroying/re-creating them. This keeps all current app state intact.
    api.rerender('very-unique-id', myComponentOptions)

    // --- OR ---

    // if a component has non-template/render options changed,
    // it needs to be fully reloaded. This will destroy and re-create all its
    // active instances (and their children).
    api.reload('very-unique-id', myComponentOptions)
  }
}

view raw JSON →