react-suspense-polyfill

Provides a basic polyfill for the upcoming React Suspense APIs.

• React.Suspense
• React.Timeout
• Support React v16
• In-depth blog post
• Suspense demo
• Thorough compatibility tests

Status

This module is intended for understanding and experimenting with the upcoming React Suspense APIs.

Note that the actual version of Suspense that will ship with React is significantly more complicated and efficient than the version in this polyfill. It is meant solely for experimental purposes and to ease the burden of incremental upgrades.

How It Works

At its core, React Suspense works by allowing an async component to throw a Promise from its render method.

This polyfill mimics React's internal support for this behavior by implementing an error boundary in the Timeout component. If the error boundary encounters a thrown Promise, it waits until that Promise resolves and then attempts to re-render its children. It also handles falling back to loading content if the Promise takes too long to resolve.

The reason this polyfill does not support React v15 is because error boundaries weren't properly supported until React v16. If you have ideas on how to add support for React v15, submit an issue and let's discuss!

Note that React will log an error to the console regarding the thrown error, but this can safely be ignored. Unfortunately, there is no way to disable this error reporting for these types of intentional use cases.

With that being said, I hope this module and accompanying demos make it easier to get up-to-speed with React Suspense. 😄

Install

npm install --save react-suspense-polyfill

Usage

The only difference between using this polyfill and a suspense-enabled version of React, is that you must import { Suspense } from react-suspense-polyfill instead of from React.

With this minor change, suspense demos and react-async-elements will function as expected.

import React, { Component } from 'react'
import ReactDOM from 'react-dom'

import { Suspense } from 'react-suspense-polyfill'

import { createCache, createResource } from 'simple-cache-provider'

const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
const cache = createCache()

// Loads the Thing component lazily
const getThing = createResource(
  () => sleep(2000).then(() => import('./Thing').then(mod => mod.default)),
  thing => thing
)

const LazyThing = props => {
  const Comp = getThing.read(cache, props)
  return <Comp {...props} />
}

class Example extends Component {
  render () {
    return (
      <React.Fragment>
        <h1>Suspense</h1>

        <Suspense delayMs={500} fallback={<div>🌀 'Loading....'</div>}>
          <LazyThing />
        </Suspense>
      </React.Fragment>
    )
  }
}

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

In this example, the following rendering steps will occur:

1. React will invoke Example's render method.
2. Suspense will get rendered which will in turn attempt to render LazyThing.
3. The LazyThing will try to load its resource from the cache but fail and throw a Promise.
4. Suspense (actually Timeout under the hood) will catch this Promise in its error boundary componentDidCatch.
5. Suspense starts waiting for that Promise to resolve and kicks off a 500ms timeout. Currently, the Suspense subtree is rendering nothing.
6. After 500ms, Suspense will timeout and display its fallback loading content.
7. After another 1500ms (2000ms total), the LazyThing resource resolves.
8. Suspense realizes it's child has resolved and again attempts to re-render its child.
9. The LazyThing component synchronously renders the previously cached Thing component.
10. All is right with the world 😃

Related

• blog post - Gives more background and a deeper explanation of how the code works.
• react-suspense-starter - Alternative which bundles a pre-built version of Suspense-enabled React allowing you to experiment with React Suspense right meow.
• react-async-elements - Suspense-friendly async React elements for common situations.
• fresh-async-react - More Suspense stuff (code, demos, and discussions).

License

MIT © transitive-bullshit