Isolated Core

A library for seamless in-page cold updates using iframes.

:zap: DEMO

Introduction

In long running web apps, such as chat clients or music players, users leave pages open for weeks. It's useful to push code updates to existing clients, but in-page updates must be extremely fast and reliable to not become disruptive to the user experience.

With Isolated Core, your client-side JS (the "core") is contained within an

• Speed: updates load in the background and "swapping cores" is extremely fast.
• Fault-tolerance: network and JS errors during init are caught before performing an update.
• Predictability: loading an update runs the same code paths as reloading the page.

Isolated Core is complementary to existing techniques like Hot Module Replacement (HMR) and is framework agnostic. Unlike HMR, Isolated Core reloads your entire app environment *cold* from a blank slate. This makes updates predictable and easy to reason about, and facilitates updating components that previously required a full page reload. In addition, Isolated Core makes rollouts safer: since updates load and initialize in the background, failures can be caught rapidly without disrupting the user.

Browser Compatibility

Isolated core works on IE9+ and all other modern browsers. IE8 support is possible but not complete -- if you need it, please file an issue!

Usage

In the entry point of your app, call

coreInit

coreInit

coreInit

run

This design makes Isolated Core compatible with a Content Security Policy and browsers which do not support Data URIs in iframes.

main.js:

import { coreInit } from 'isolated-core'

coreInit({
  // In non-IE, you can use document.currentScript.src here.
  scriptURL: '/main.js',
  // Note: we are deferring require()ing our code until the "run" function
  // executes inside the iframe. Our init function is exported by index.js.
  run: core => require('./').init(core),
})

In your initialization function, take a

core

core.ready()

attach

detach

index.js:

import React from 'react'
import ReactDOM from 'react-dom'
import MyComponent from './MyComponent'

export function init(core) {
  core.ready({
    attach(uidocument) {
      ReactDOM.render(, uidocument.getElementById('container'))
    },
detach(uidocument) {
  ReactDOM.unmountComponentAtNode(uidocument.getElementById('container'))
},
  })
}

When

coreInit

To load an update, call

loadCore

onerror

loadCore

coreInit

core.ready()

loadCore({
  scriptURL: '/main.js',
}).then(
  function success(coreRef) => {
    // Call launchCore to detach the current core and attach the new one.
    coreRef.launchCore()
  },

  function failure(coreErr) {
    // coreErr.type will be either "request" or "js"
    // "request" type errors have a "src" property with the URL that failed to load.
    // "js" type errors have an "err" property with the exception.
    console.error(core #${coreErr.id} failed to load: ${coreErr.type} error)
// Call destroyCore to remove the iframe from the document.
coreErr.destroyCore()
  }
)

You should use CSS to hide core iframes. The easiest way to do it is to match the

data-coreid

iframe[data-coreid] { display: none }

Caveats

While in general the Isolated Core pattern provides a lot of benefits, there are a few trade-offs worth mentioning:

• Cores typically share the same browser thread for a page, so if an update initializing in the background ties up the thread, it can cause framerate drops or pauses in the UI.

• By its nature, cold loading requires more initialization time and memory than hot replacing modules. When a core is ready but not attached yet, it adds significant memory footprint to the page.

• It's necessary to set aggressive HTTP caching headers for your core script because it will be loaded in both the initial page and then immediately again inside the first core iframe. For best results, use a CDN and include the hash of your bundles in the filename.

API

coreInit({ scriptURL, run, args })

Initialize a core, creating an iframe on first page load if necessary.

When called outside a core iframe,

coreInit

loadCore

When called inside a core iframe,

coreInit

run

core

{
  id: 0,              // A unique numeric id for the core
  args: {...},        // An object passed to loadCore by the invoking context
  ready: ,  // Call with a handlers object when finished loading
}

The

core.ready()

run

core.ready({
  attach(uidocument) {
    // render your UI to uidocument
  }

  detach(uidocument) {
    // clean up your event handlers, etc.
  }
})

loadCore({ scriptURL, args })

Load a new core with specified

args

scriptURL

When the promise resolves or rejects, it passes an object of the form:

{
  id: 0,                    // A unique numeric id for the core
  args: {...},              // The args object you specified
  context: ,        // A reference to the window object of the iframe
  destroyCore: ,  // Call to remove the core's iframe
}

If the promise resolves, the return type will also include:

{
  launchCore: ,   // Call to detach the current core and attach this new one
}

Calling

launchCore

launchCore

If the promise rejects, the return type will also include:

{
  type: 'request'|'js',     // Either 'request' on network error, or 'js' on exception
  src: ,               // If type: 'request', the URL that failed to load
  err: ,             // If type: 'js', the exception object thrown
}

License

MIT