Babel-plugin-ng-hot-reload NPM

🔥 babel-plugin-ng-hot-reload

A babel plugin which enables hot module replacement in AngularJS applications. The plugin is based on the ng-hot-reload webpack loader but is rewritten as babel plugin so that it is compatible with es-module syntax and every bundler which supports the hot-replacement API (e.g. webpack or parcel).

Getting started

To see it in action you can simply checkout the examples on CodeSandbox:
Webpack / JavaScript demo on CodeSandbox
Webpack / TypeScript demo on CodeSandbox
Parcel / TypeScript demo on CodeSandbox (There is an issue with HTML import, see: FAQ)

npm i -D babel-plugin-ng-hot-reload     # npm or
yarn add -D babel-plugin-ng-hot-reload  # yarn

Add the following to your babelrc.js file:

// without options
module.exports = {
  plugins: ['babel-plugin-ng-hot-reload'],
};

// with options
module.exports = {
  plugins: [
    [
      'babel-plugin-ng-hot-reload',
      {
        angularGlobal: false,
        forceRefresh: true,
        preserveState: true,
        angularReference: "require('angular'), angular",
      },
    ],
  ],
};

Options

Option	Default	Description
`angularGlobal`	`false` (false or string)	Define whether angular is provided as global variable. Set to `'angular'` when `angular` is your global variable.
`forceRefresh`	`true` (boolean)	Whether to reload window automatically when a change in source files can't be hot-reloaded. Note that Webpack DevServer also has its own option hotOnly, which should also be configured correctly to get the behaviour you want when hot reloading fails.(ng-hot-reload option)
`preserveState`	`true` (boolean)	If true, the library attempts to preserve some state in scope and controller instances when they are reloaded. Preserving state is an experimental feature and quite "hackish" so it may cause problems in some cases. Setting this to `false` might help if you run into weird errors.(ng-hot-reload option)
`angularReference`	`"require('angular'), angular"` (string)	JavaScript expression that will be evaluated to get a reference to angular.(ng-hot-reload option)

FAQ

Use together with `@babel/preset-env`

This plugin should work nicely together with the @babel/preset-env plugin. In opposite to the original ng-hot-reload webpack-loader it's not required to transpile your code to commonjs modules:

module.exports = {
  presets: [
    [
      '@babel/preset-env',
      {
        modules: false, // Don't transpile the modules (default)
      },
    ],
  ],
  plugins: ['babel-plugin-ng-hot-reload'],
};

For an example check out the Webpack / Javascript example.

Use AngularJS as global variable

Per default the plugin looks for imports of 'angular'-package and only adds the hot-module-reload code to this modules. However in some environments angular is used as a global variable without beeing imported, so the plugin has a angularGlobal setting which supports the use of angular as a global variable:

// Default mode: Add hot-module-reload only to files which import 'angular'
// app.module.js
import * as angular from 'angular'; // or
import angular from 'angular'; // or
import 'angular';

angular.module('hot-reload-demo', []);

////////////////////////////////////////////////////////////////////////////////

// Setting angularGlobal option: Use `angular` as global variable
// .babelrc.json
module.exports = {
  plugins: [
    [
      'babel-plugin-ng-hot-reload',
      {
        angularGlobal: 'angular', // Name of the global angular variable
      },
    ],
  ],
};

// app.module.js
angular.module('hot-reload-demo', []);

For an example check out the Webpack / Javascript example.

Use together with `ngAnnotate`

When you are using this plugin together with babel-plugin-angularjs-annotate make sure that the ngAnnotate plugin is added before this plugin in your .babelrc.js:

module.exports = {
  plugins: ['angularjs-annotate', 'babel-plugin-ng-hot-reload'],
};

For an example check out the Webpack / TypeScript example.

Known issues with parcel

Since this plugin only requires babel, you can use every build tool which supports hot-module-replacement. You can check out the Parcel / TypeScript example to see how it works with other bundlers than webpack.

Unfortunatly there is currently an issue related to parcel: