Building a Polyfill for React Suspense

Intro

If you only care about the codes, check out react-suspense-polyfill, otherwise here we go!

Setting the Stage

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

React.Suspense

import React from 'react'
import PropTypes from 'prop-types'
import Timeout from './timeout'

export default function Suspense (props) {
  const {
    delayMs,
    fallback,
    suspense,
    children
  } = props

  return (
    <Timeout ms={delayMs} suspense={suspense}>
      {didExpire => (didExpire ? fallback : children)}
    </Timeout>
  )
}

Suspense.propTypes = {
  delayMs: PropTypes.number,
  fallback: PropTypes.node,
  suspense: PropTypes.node,
  children: PropTypes.node
}

Suspense.defaultProps = {
  fallback: null,
  suspense: null,
  children: null
}

• delayMs - Amount of time in milliseconds to wait before displaying fallback / loading content. The main reason for adding a delay before displaying fallback content is to prevent loading indicators flashing too quickly before the main async content loads which can be an annoying UI distraction.

• fallback - A React Node that will be displayed while any child component is loading only after delayMs have elapsed. This will typically be some type of loading spinner.

• suspense - A React Node that will be displayed while any child component is loading only before delayMs have elapsed. Note: this optional prop is specific to react-suspense-polyfill and is strictly for the purpose of demoing how suspense works.

• children - A React Node that represents the main content of this Suspense component which may or may not throw a Promise while loading asynchronous resources. See react-async-elements for some examples of super sexy, async-friendly child components.

React.Timeout

import { Component } from 'react'
import PropTypes from 'prop-types'

export default class Timeout extends Component {
  static propTypes = {
    ms: PropTypes.number,
    suspense: PropTypes.node,
    children: PropTypes.func.isRequired
  }

  static defaultProps = {
    ms: 0,
    suspense: null
  }

  state = {
    inSuspense: false,
    didExpire: false
  }

  _expireTimeout = null
  _suspender = null

  componentDidCatch(err, info) {
    if (typeof err.then === 'function') {
      const suspender = err
      this._suspender = suspender
      this._initTimeout()
      this.setState({ inSuspense: true })

      const update = () => {
        if (this._suspender !== suspender) return
        this.setState({ inSuspense: false })
        this._clearTimeout()

        if (this.state.didExpire) {
          this.setState({ didExpire: false })
        } else {
          this.forceUpdate()
        }
      }

      suspender.then(update, update)
    } else {
      // rethrow non-promise errors
      throw err
    }
  }

  render() {
    const {
      children,
      suspense
    } = this.props

    const {
      inSuspense,
      didExpire
    } = this.state

    if (inSuspense && !didExpire) {
      // optional: strictly for the purpose of demoing how suspense works
      return suspense
    } else {
      return children(didExpire)
    }
  }

  _initTimeout() {
    const {
      ms
    } = this.props

    this._clearTimeout()

    this._expireTimeout = setTimeout(() => {
      this.setState({ didExpire: true })
    }, ms)
  }

  _clearTimeout() {
    if (this._expireTimeout) {
      clearTimeout(this._expireTimeout)
      this._expireTimeout = null
    }
  }
}

1. The render method (Line 50) will initially invoke its children render function with a boolean value signifying whether or not this component has hit its timeout ms since mounting and encountering an async workload.

2. If the children render successfully, all is well with the world and React continues on as normal. 😃

3. If any component within the children subtree throws a Promise from its render method, it will be caught by Timeout’s error boundary, componentDidCatch (Line 24).

4. The error handler first starts a timeout for this async work (Line 28), such that the Timeout will fall back to displaying loading content if & when the ms timeout expires.

5. During the ms time before this Promise may expire, the Timeout is “in suspense” (Lines 29 and 63), which essentially means that we’re waiting for some resource to load but it hasn’t taken long enough to justify displaying the fallback / loading content just yet.

6. Once the Promise resolves (Line 43), Timeout once again invokes its children render prop (Line 39) with the expectation that this time, the initial asynchronous resource will resolve synchronously and all will once again be well with the world. 😃

Comparison to React Suspense

Correctness

Efficiency

Wrapping Up

• Creating React Suspense in v16.2 - Similar experiment by Pete Gleeson.

• react-suspense-starter - Alternative which bundles a pre-built version of Suspense-enabled React allowing you to experiment with React Suspense right meow. By Jared Palmer.

• react-async-elements - Suspense-friendly async React elements for common situations. By Jared Palmer.

• fresh-async-react - More Suspense stuff (code, demos, and discussions). By Swyx.