Home

Awesome

react-async-component 📬

Resolve components asynchronously, with support for code splitting and advanced server side rendering use cases.

npm MIT License Travis Codecov

const AsyncProduct = asyncComponent({
  resolve: () => System.import('./Product'),
  LoadingComponent: ({ productId }) => <div>Loading {productId}</div>, // Optional
  ErrorComponent: ({ error }) => <div>{error.message}</div> // Optional
});

<AsyncProduct productId={1} /> // 🚀

TOCs

Introduction

This library does not require that you use either Webpack or Babel. Instead it provides you a generic and "pure" Javascript/React API which allows for the expression of lazy-loaded Components. It's Promise-based API naturally allows you to take advantage of modern code splitting APIs (e.g import(), System.import, require.ensure).

Features

Usage

Imagine you had the following Product component:

export default function Product({ id }) {
  return <div>Product {id}</div>
}

To make this asynchronous create a new file that wraps it with asyncComponent, like so:

import { asyncComponent } from 'react-async-component';

export default asyncComponent({
  resolve: () => System.import('./Product')
});

I recommend that you use the following folder/file structure:

 |- components
    |- AsyncProduct
       |- index.js   // contains asyncComponent
       |- Product.js // The component you want resolved asynchronously

Now, you can simply import AsyncProduct anywhere in your application and use it exactly as you would any other component.

For example:

import AsyncProduct from './components/AsyncProduct'

export default function MyApp() {
  return (
    <div>
      <h1>Welcome to My App</h1>
      <AsyncProduct id={1337} />
    </div>
  )
}

API

asyncComponent(config)

The asynchronous component factory. Config goes in, an asynchronous component comes out.

Arguments

Returns

A React Component.

Examples

LoadingComponent
export default asyncComponent({
  resolve: () => import('./Product'),
  LoadingComponent: ({ id }) => <div>Loading product {id}</div>
})
ErrorComponent
export default asyncComponent({
  resolve: () => import('./Product'),
  ErrorComponent: ({ error }) => <div>{error.message}</div>
})
Named chunks
export default asyncComponent({
  resolve: () => new Promise(resolve =>
    // Webpack's code splitting API w/naming
    require.ensure(
      [],
      (require) => {
        resolve(require('./Product'));
      },
      'ChunkName'
    )
  )
})

<AsyncComponentProvider />

Currently only useful when building server side rendering applications. Wraps your application allowing for efficient and effective use of asynchronous components.

Props

createAsyncContext()

Creates an asynchronous context for use by the <AsyncComponentProvider />. The context is an object that exposes the following properties to you:

Server Side Rendering

NOTE: This section only really applies if you would like to have control over the behaviour of how your asyncComponent instances are rendered on the server. If you don't mind your asyncComponents always being resolved on the client only then you need not do any of the below. In my opinion there is great value in just server rendering your app shell and having everything else resolve on the client, however, you may have very strict SEO needs - in which case, we have your back.

This library has been designed for interoperability with react-async-bootstrapper.

react-async-bootstrapper allows us to do a "pre-render parse" of our React Element tree and execute an asyncBootstrap function that are attached to a components within the tree. In our case the "bootstrapping" process involves the resolution of asynchronous components so that they can be rendered "synchronously" by the server. We use this 3rd party library as it allows interoperability with other libraries which also require a "bootstrapping" process (e.g. data preloading as supported by react-jobs).

Firstly, install react-async-bootstrapper:

npm install react-async-bootstrapper

Now, let's configure the "server" side. You could use a similar express (or other HTTP server) middleware configuration:

import React from 'react'
import { renderToString } from 'react-dom/server'
import { AsyncComponentProvider, createAsyncContext } from 'react-async-component' // 👈
import asyncBootstrapper from 'react-async-bootstrapper' // 👈
import serialize from 'serialize-javascript'

import MyApp from './shared/components/MyApp'

export default function expressMiddleware(req, res, next) {
  //    Create the async context for our provider, this grants
  // 👇 us the ability to tap into the state to send back to the client.
  const asyncContext = createAsyncContext()

  // 👇 Ensure you wrap your application with the provider.
  const app = (
    <AsyncComponentProvider asyncContext={asyncContext}>
      <MyApp />
    </AsyncComponentProvider>
  )

  // 👇 This makes sure we "bootstrap" resolve any async components prior to rendering
  asyncBootstrapper(app).then(() => {
      // We can now render our app 👇
      const appString = renderToString(app)

      // Get the async component state. 👇
      const asyncState = asyncContext.getState()

      const html = `
        <html>
          <head>
            <title>Example</title>
          </head>
          <body>
            <div id="app">${appString}</div>
            <script type="text/javascript">
              // Serialise the state into the HTML response 👇
              window.ASYNC_COMPONENTS_STATE = ${serialize(asyncState)}
            </script>
          </body>
        </html>`

      res.send(html)
    })
}

Then on the "client" side you would do the following:

import React from 'react'
import { render } from 'react-dom'
import { AsyncComponentProvider, createAsyncContext } from 'react-async-component' // 👈
import asyncBootstrapper from 'react-async-bootstrapper' // 👈
import MyApp from './components/MyApp'

// 👇 Get any "rehydrate" state sent back by the server
const rehydrateState = window.ASYNC_COMPONENTS_STATE

//   Ensure you wrap your application with the provider,
// 👇 and pass in the rehydrateState.
const app = (
  <AsyncComponentProvider  rehydrateState={rehydrateState}>
    <MyApp />
  </AsyncComponentProvider>
)

//   We run the bootstrapper again, which in this context will
//   ensure that all components specified by the rehydrateState
// 👇 will be resolved prior to render.
asyncBootstrapper(app).then(() => {
  // 👇 Render the app
  render(app, document.getElementById('app'))
});

SSR AsyncComponent Resolution Process

It is worth us highlighting exactly how we go about resolving and rendering your asyncComponent instances on the server. This knowledge will help you become aware of potential issues with your component implementations as well as how to effectively use our provided configuration properties to create more efficient implementations.

When running react-async-bootstrapper on the server the helper has to walk through your react element tree (depth first i.e. top down) in order to discover all the asyncComponent instances and resolve them in preparation for when you call the ReactDOM.renderToString. As it walks through the tree it has to call the componentWillMount method on your Components and then the render methods so that it can get back the child react elements for each Component and continue walking down the element tree. When it discovers an asyncComponent instance it will first resolve the Component that it refers to and then it will continue walking down it's child elements (unless you set the configuration for your asyncComponent to not allow this) in order to try and discover any nested asyncComponent instances. It continues doing this until it exhausts your element tree.

Although this operation isn't as expensive as an actual render as we don't generate the DOM it can still be quite wasteful if you have a deep tree. Therefore we have provided a set of configuration values that allow you to massively optimise this process. See the next section below.

SSR Performance Optimisation

As discussed in the "SSR AsyncComponent Resolution Process" section above it is possible to have an inefficient implementation of your asyncComponent instances. Therefore we introduced a new configuration object property for the asyncComponent factory, called serverMode, which provides you with a mechanism to optimise the configuration of your async Component instances. Please see the API documentation for more information.

Understand your own applications needs and use the options appropriately . I personally recommend using mostly "defer" and a bit of "boundary". Try to see code splitting as allowing you to server side render an application shell to give the user perceived performance. Of course there will be requirements otherwise (SEO), but try to isolate these components and use a "boundary" as soon as you feel you can.

Demo

You can see a "live" version here. This is a deployment of the "React, Universally" starter kit that makes use of this library. Open the network tab and then click the menu items to see the asynchronous component resolving in action.

FAQs

Let me know if you have any...