gem-hunter

rollup-plugin-hot

Work in progress

Try it

git clone git@github.com:rixo/rollup-plugin-hot.git
# ATTENTION run from the example dir for a quick demo
cd rollup-plugin-hot/example
yarn
yarn dev

Install

npm install --dev rollup-plugin-hot

yarn add --dev rollup-plugin-hot

Config

export default {
  output: {
    // supports either dir or file
    dir: 'public', // writes individual modules to public/@hot/
    file: 'public/bundle.js', // ... to public/bundle.js@hot/

    // format will be overridden to 'system' when HMR is running
    format: 'iife',

    // sourcemapping is supported
    sourcemap: true,
  },
  plugins: [
    ...hmr({
      // When false, the plugin will do nothing at all (useful for prod build).
      enabled: true, // Default: true

      // When false, only the dev server will run. The plugin will not mess with
      // your config, your bundle, or transform any code. Only reload the
      // browser when the bundle changes.
      hot: false, // Default: true

      // These two are used to map output filenames to URLs, because Rollup
      // knows about filenames but SystemJS knows about URLs.
      //
      // FS path to public directory
      // NOTE this is only used to compute URLs from FS paths... see mount
      // option bellow if you want to serve static content
      public: 'public', // Default: ''
      // Base URL
      baseUrl: '/', // Default: '/'

      // Change the host / port of the dev server
      port: 12345, // Default: 33440
      host: '0.0.0.0', // Default: 'localhost'
      // Prevent from falling back on a random port if the specified one is
      // already occupied
      randomPortFallback: false, // Default: true

      // Opens the dev server in a new browser tab if set.
      // If Chrome is available on macOS, an attempt will be made to
      // reuse an existing browser tab. Any installed browser may also be specified.
      // E.g., “default“, “chrome”, “firefox”, “brave”. Set “none” or `false` to disable.
      open: 'default', // Default: false

      // Page to navigate to when opening the browser.
      // Will not do anything if open=false.
      // Remember to start with a slash.
      openPage: '/different/page', // Default: baseUrl
      // The hostname & port where the browser tab will be open.
      openHost: 'localhost', // Default: HMR server host
      openPort: '33000', // Default: HMR server port

      // Define different paths that should be proxied, and where they should be proxied to.
      // See https://github.com/villadora/express-http-proxy for configuration options.
      //
      // Path Propagation:
      // { "/a": "http://localhost" }
      // - /a   => http://localhost
      // - /a/b => http://localhost/b
      //
      // { "/a": "http://localhost/x" }
      // - /a   => http://localhost/x
      // - /a/b => http://localhost/x/b
      proxy: {
        // Short form:
        '/api/01': 'https://pokeapi.co/api/v1',
        // With options:
        '/api/02': ['https://pokeapi.co/api/v2', { proxyReqPathResolver(req) { /* ... */ } }],
      },

      // Serve additional static content: the key is a FS path, the value is
      // the base URL. Static content will always be served _after_ files from
      // the bundle.
      mount: {
        public: '/',
        'relative/path/to/somewhere': '/base-url/',
      },

      // Write bundle files in RAM instead of FS and serve them through the dev
      // server. This is obviously more performant but there may be cross domain
      // issues. Also, for very big apps, this might consume too much memory.
      inMemory: true, // Default: false
      // If you sill want to write do disk when using inMemory.
      write: true, // Default: !inMemory

      // Prevent full reload on HMR errors. HMR updates will keep being applied
      // and, most probably, crash more & more. By changing this, you expose
      // yourself to a very broken HMR experience...
      reload: false,
      // Or fine grained (will be deep merged in the defaults bellow).
      // 'defer' means the reload will happen on the next HMR update.
      reload: {
        // When an HMR update bubbles up beyond an entry point without finding
        // an accept handler
        unaccepted: true,
        // Errors during module initialization (i.e. in your code)
        moduleError: 'defer',
        // HMR specific errors (i.e. errors that happens in HMR accept handlers)
        acceptError: true,
        // Other errors during application of hot update (i.e. most probably in
        // my code -- this plugin)
        error: true,
        // When connection to HMR server is lost, then resumes. This typically
        // means that you've restarted Rollup. HMR could theoretically resume
        // and work correctly, provided nothing has changed on the server (but
        // why restart Rollup if nothing has changed? hence defaults to reload).
        reconnect: true,
      },

      // By default, when an update is not accepted the root modules (i.e. those
      // that have no import parents) are automatically accepted. This means
      // that every module will be hot reloaded. You can turn this off to do
      // a full reload instead.
      //
      // Note: an update is "not accepted" when the whole module tree has been
      // traversed, starting from the changed module, up to the root module(s),
      // and no accept handlers have been found.
      autoAccept: false, // Default: true

      // Clear console after successful HMR updates (Parcel style)
      clearConsole: true, // Default: false

      // --- Advanced ---

      // Defaults to output.file. Must be under public dir.
      // Only used when output.file is set.
      loaderFile: 'public/bundle.js',
    }),
  ],
}

How it works

input: 'src/main.js',
output: {
  file: 'public/bundle.js',
},
plugins: [
  hmr({
    public: 'public',
    baseUrl: '/',
  })
]

// TODO There should be an option not to inject SystemJS loader for people
//      already using it in their app

... // SystemJS loader

... // HMR runtime

System.import('/bundle.js@hot/main.js')

The "hot API"

const previousDisposeData = module.hot.data
module.hot.dispose(data => { ... }) // run a handler on dispose
module.hot.accept(errorHandler) // self-accept HMR updates for this module
module.hot.decline() // reject any update that touches this module
// plus a whole lot more of other things

const previousDisposeData = import.meta.hot.data
import.meta.hot.dispose(async data => { ... })
import.meta.hot.accept(async acceptHandler)
import.meta.hot.decline() // MAYBE
import.meta.hot.catch(async errorHandler) // DUNNO
// and that's all

API

import.meta.hot

if (import.meta.hot) {
  // HMR specific stuff...
}

import.meta.hot.data

import.meta.hot.dispose(async data => void)

if (import.meta.hot) {
  // will be undefined when the first version of the module is initally loaded
  console.log(import.meta.hot.data)

  // restore previous state, or init to 0
  const state = (import.meta.hot.data && import.meta.hot.data.value) || 0

  import.meta.hot.dispose(data => {
    // increment the value on HMR update (for illustration purpose)
    // NOTE mutate the passed data object
    data.value = state + 1
  })
}

import.meta.hot.accept(function|void)

// simply accept the HMR update -- just reexecuting the module must be enough to
// reflect any code change, or this will result in a broken app state
import.meta.hot.accept()

// in most case, you'll need to pass
import.meta.hot.accept(({ id, bubbled }) => {
  // id is the id of the updated module
  //
  // bubbled will be true if this handler is called because a HMR update
  // has bubbled up to this module (you cannot conclude that this module has not
  // changed too, though)
  //
  // ... your code to apply the update
})

import.meta.hot.beforeUpdate and import.meta.hot.afterUpdate

if (import.meta.hot) {
  let scrollTopBefore = null

  import.meta.hot.beforeUpdate(() => {
    scrollTopBefore = document.body.scrollTop
  })

  import.meta.hot.afterUpdate(() => {
    requestAnimationFrame(() => {
      document.body.scrollTop = scrollTopBefore
    })
  })
}

License