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:
- React will invoke
Example
'srender
method. Suspense
will get rendered which will in turn attempt to renderLazyThing
.- The
LazyThing
will try to load its resource from the cache but fail and throw aPromise
. Suspense
(actuallyTimeout
under the hood) will catch thisPromise
in its error boundarycomponentDidCatch
.Suspense
starts waiting for that Promise to resolve and kicks off a 500ms timeout. Currently, theSuspense
subtree is rendering nothing.- After 500ms,
Suspense
will timeout and display itsfallback
loading content. - After another 1500ms (2000ms total), the
LazyThing
resource resolves. Suspense
realizes it's child has resolved and again attempts to re-render its child.- The
LazyThing
component synchronously renders the previously cachedThing
component. - 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