README

SystemJS Hot Reloader

This hot reloader is compatbile with SystemJS v0.19.x only for now

Universal hot reloader for SystemJS / JSPM.

This is more powerfull alternative to capaj/systemjs-hot-reloader.

Featured demo is available here: https://github.com/sormy/jspm-hot-skeleton.git

Features

Designed to be used together with bs-systemjs-hot-reloader package which will be responsible for
- development web server
- watch for file changes and emit reload event to this module
- track CSS/LESS/SASS/SCSS/Stylus dependencies
Reload js, jsx, ts, tsx etc on the fly with all related modules
Reload CSS/LESS/SASS/SCSS/Stylus if plugin supports hot reload
Console status logging like in webpack
Track errors during reload and revert back on errors
Custom __reload() / __unload() hooks
Unload unused modules (mostly usefull for css modules). SystemJS.trace = true is required to track modules without exports.
Optimize reload strategy based on full dependency graph
Works with/without enabled SystemJS.trace
React Hot Loader v3.x friendly

TODO

Add tests
Test for support with different JSPM / SystemJS versions
Fancy error screen (react-redbox ?)
Show BrowserSync notification on reload
Show BrowserSync notification for hooks (__reload() and __unload())
Assume that some modules like scss|sass|less|style have no exports (so reloading them will not cause reload for modules which imports them)
Babel plugin to strip __unload() / __reload() for production builds
Show list of unloaded modules
Get rid of react hot loader babel plugin
Reload assets (fonts, images, cursors etc)

Installation

npm install browser-sync bs-systemjs-hot-reloader --save-dev
jspm install npm:systemjs-hot-reloader-ex --dev

Usage

Please refer to bs-systemjs-hot-reloader usage to setup BrowserSync with plugin.

It is peer dependency for bs-systemjs-hot-reloader, but tehnically could be used as client side reloader for any 3rd party development server.

Log Level

Log level could be changed on the fly with:

// Log level: 0 - none, 1 - error, 2 - info (default), 3 - debug
SystemJS.import('systemjs-hot-reloader-ex')
  .then(function (exports) {
    exports.default.logLevel = 3;
  });

or via jspm.config.js:

SystemJS.config({
  hotReloaderOptions: {
    logLevel: 3
  }
});

JavaScript Hot Reloader

This reloader could reload any JS module and will track all dependencies.

By default this reloader will recursively all parents of modified module and will reinject all modules.

Modules with side effects should export __unload() hook.

Modules with alternative reload logic should export __reload() hook.

Both hooks have array of reinjected modules as first argument.

Please note that unused modules without exports can't be unloaded without extra debug information which could be enable with SystemJS.trace = true.

CSS Hot Reloader

This reloader could reload any module, including CSS, LESS, SCSS, SASS, Stylus, PostCSS if css plugin supports correct reinjection.

Server side bs-systemjs-hot-reloader could track LESS, SCSS, SASS, Stylus dependency tree to reload root module if one of dependencies is changed.

If you would like to be able to remove CSS modules on the fly after they were initially loaded then you need to enable SystemJS.trace = true. Module to DOM relations are tracked with selectors: [data-url={address}] and [data-systemjs-css, href={address}].

Avoid using of loaders via ! because in that case there is no 100% way to convert file name into module name so reloader will have to iterate over all registered modules to find correct module name. It is recommended to define loader via meta SystemJS config section for files based on their extension.

The fastest reload is guaranteed when css filename could be 1:1 resolved to module name. It works when you have css loading workflow like below:

SystemJS.config({
  meta: {
    "*.css": { "loader": "plugin-css" },
    "*.scss": { "loader": "plugin-sass" },
    "*.sass": { "loader": "plugin-sass" },
    "*.less": { "loader": "plugin-less" }
  },
});

import 'app.css';
import 'component.scss';

A slightly slower loading workflow (guess loader by adding ! to filename in resolver):

import 'app.css!';
import 'component.scss!';

The slowest loading workflow (need to search in all loaded modules):

import 'app.css!plugin-css';
import 'component.scss!plugin-sass';

By default this hot reloader will try to free resources occupued by style/link tag with css before reload, so it will drop link/style tag and expects that loader plugin will be able to reinject style/link tag with css. That could cause changing order of style/link tags after hot reload. If you would like to disable this behaviour then pass clearResources = false:

SystemJS.config({
  hotReloaderOptions: {
    clearResources: false
  }
});

React Hot Reloader

If you keep state in store model object or in mobx and your application will be able to restore state from it, then you don't need this part, just keep you store instance in separate module.

React, babel plugin, babel preset are required (obviously):

jspm install react react-dom
jspm install plugin-babel babel-preset-react --dev

We could use WebPack's react hot reloader.

jspm install npm:react-hot-loader@3.0.0-beta.6 --save-dev

React Hot Reloader v3.x is the best hot reloader and it uses the best things from both react-transform-hmr and react-hot-loader v1.x - v2.x

How does it work:

react-hot-loader/babel babel plugin is required to wrap import()
react-hot-loader/lib/patch.dev.js is required, will patch React on the fly
react-hot-loader/lib/AppContainer.dev.js will restore state on reload
__reload() hook required to rerender application instead of full module reload
different application entry points for development and production

Please note, that react-hot-loader/babel should be FIRST plugin in list of Babel plugins.

File: jspm.config.js:

SystemJS.config({
  paths: {
    "app/": "src/"
  },
  meta: {
    "*.jsx": { loader: "plugin-babel" }
  },
  trace: true, // fix me?
  transpiler: "plugin-babel",
  babelOptions: {
    "presets": [
      "babel-preset-react"  // fix me
    ]
  },
  browserConfig: {
    "babelOptions": {
      "plugins": [
        "react-hot-loader/babel"
      ]
    },
    "packages": {
      "app": {
        "main": "index.jsx"
      }
    }
  },
  packages: {
    "app": {
      "main": "index.dist.jsx",
      "defaultExtension": "jsx"
    }
  }
});

File: src/index.jsx (development entry point):

import React from 'react';
import ReactDOM from 'react-dom';

import 'react-hot-loader/lib/patch.dev.js';
import AppContainer from 'react-hot-loader/lib/AppContainer.dev.js';

import App from './App';

const root = document.getElementById('root');

ReactDOM.render(<AppContainer><App /></AppContainer>, root);

export function __reload() {
  ReactDOM.render(<AppContainer><App /></AppContainer>, root);
}

File: src/index.dist.jsx (production entry point):

import React from 'react';
import ReactDOM from 'react-dom';

import App from './App';

ReactDOM.render(<App/>, document.getElementById('root'));

File: ./index.html (development entry point):

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Application</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="jspm_packages/system.js"></script>
    <script src="jspm.config.js"></script>
    <script>SystemJS.import('app');</script>
  </body>
</html>

File: ./index.dist.html (production entry point):

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Application</title>
  </head>
  <body>
    <div id="root"></div>
    <script src="app.js"></script>
  </body>
</html>

Usage no npm install needed!