react-broker

A lightweight library for lazy components using React 16.8+. It's perfect for code splitting and has the simplest SSR story you've ever seen out-of-the-box.

Critically, this package is only intended to work with Webpack, specifically Webpack 4 and future versions. There are no plans to implement a design accommodating Parcel or other bundlers. There is also a hard requirement for babel-plugin-macros (which is shipped with CRA) if you opt to use the macro.

import {BrokerProvider} from 'react-broker'
import lazy from 'react-broker/macro'

// Automatically generates dynamic imports for webpack with babel-plugin-macros. 
// Just give it the path.
const LazyPage = lazy('../pages/Page', {loading: props => 'Loading...'})

////////////////////////////////////////////////////////////////////////////////
//                               ⬇ BECOMES ⬇                                //
///////////////////////////////////////////////////////////////////////////////

const LazyPage =
  require('react-broker').lazy(
    'src/pages/Page',
    () => import(/* webpackChunkName: "src/pages/Page" */ '../pages/Page'),
    {loading: props => 'Loading...'}
  )
  
function App () {
  // Look at me! I'm used like a normal component.
  return (
    <BrokerProvider>
      <LazyPage id='1'/>
    </BrokerProvider/>
   )
}

Requirements

• Webpack 4+ (because chunks)
• React 16.8+ (because hooks)
• Babel (because babel-plugin-macros)

Installation

yarn add react-broker or npm i react-broker

Examples

Hello world
Hello world w/ Router

Documentation

react-broker/macro

The function that transforms your imports and delegates your async components.

import lazy from 'react-broker/macro'

lazy(component <String>, options <Object>)

component {String}
A path to a React component you want to lazy load. The component must be in the default export of the file.

Paths cannot be passed via an identifier, it has to be a plain string. It is used just like a regular component.

You may also lazy load external library components, but just know that the component in question must be the default export.

// Used like a regular component
const LazyPage = lazy('./pages/Home', {loading: props => 'Loading ${props.id}...'})

<LazyPage id={1}>
  // ...
</LazyPage>

options {Object}

• loading (props, context{retry, error})
  • props props passed the component
  • context
    • retry is a function which will force a reload of the component
    • error is any error returned by Promise.reject, this is only relevant if an error component isn't also defined in options
• error (props, context{retry, error})
  • See loading

Broker.Provider

Manages code-splitting and the resolution of your async components by keeping track of which chunk names have been loaded and also determining which <scripts> need to be included from the server-side. Broker.Provider must be defined at the top-level of your lazy loaded components.

Props

chunkCache {Broker.createChunkCache}

You only provide a chunkCache on the server side. In the client it is not allowed. The chunk cache is used for tracking which chunks were loaded during the latest render phase of the app. Broker.createChunkCache

import * as Broker from 'react-broker'

const chunkCache = Broker.createChunkCache()

function App (props) {
  return (
    <Broker.Provider chunkCache={chunkCache}>
      <LazyPage id={props.id}/>
    </Broker.Provider>
  )
}

Broker.createChunkCache

Creates a context for Broker.Provider to track chunks in and provides helper methods to provide access to those chunks.

createChunkCache.getChunkNames()

Returns an array of all the Webpack chunk names loaded into the current app.

createChunkCache.getChunks(webpackStats)

Returns a Set of all the Webpack chunks loaded into the current app.

• webpackStats <Object>
  • The stats object created by Webpack.

createChunkCache.getChunkScripts(webpackStats, options)

Returns a string representation of all the <script> tags to include in the output of your app when using with SSR.

• webpackStats {Object}
  • The stats object created by Webpack.
• options {Object}
  • preload {Bool|Object}
    • If true, this will generate <link rel='preload'> tags with your scripts.
    • If an object, the key/value pairs will be added to the <link rel='preload'> tags as attributes. e.g. {preload: {crossorigin: 'anonymous'}} generates <link rel='preload' as='script' crossorigin='anonymous' href='...'>
  • async {Bool}
    • If true, an async flag will be added to your <script> tags
    • default true
  • defer {Bool}
    • If true, a defer flag will be added to your <script> tags and async will be omitted
    • default false

See the SSR section for an example

Broker.lazy

This is the function created by react-broker/macro.

To skip the macro you could do something like this with the Webpack code-splitting API:

import {lazy} from 'react-broker'
const Component = lazy(
  'uniqueChunkName', 
  () => import(/* webpackChunkName: "uniqueChunkName" */'./path/to/component'), 
  {loading: props => 'Loading...'}
)

Lazy.load()

Preloads the component.

const LazyPage = lazy('./pages/Home')
// ...
<Link onMouseEnter={LazyPage.load}>
  Home
</Link>

Broker.load(...components <String>)

Preloads one or several Lazy components.

import * as Broker from 'react-broker'
import lazy from 'react-broker/macro'

const LazyA = lazy('./A')
const LazyB = lazy('./B')

Broker.load(LazyA, LazyB).then(/*...*/)

Broker.loadAll(

App: React.Element,

renderer: ReactDOM.renderToStaticMarkup|renderToString

)

Tracks all of the chunks used in your app during the server side render and optionally renders your app to a string

• App {React.Element}
  • Your React application
• renderer {ReactDOM.renderToStaticMarkup|ReactDOM.renderToString}
  • default ReactDOM.renderToStaticMarkup
  • The renderer used for determining the chunks used in your app. To avoid, extra renders, you could change this to `ReactDOM.renderToString.

See the SSR section for an example

Broker.loadInitial(chunkCache: Broker.createChunkCache)

Populates your chunk cache with the async components present in your application. This requires that Broker.getChunkScripts was used on the server side. The primary use case for this function is elimination loading components and flashes when initially rendering your app in the browser.

See the SSR section for an example

Server-side Rendering

client/render.js

import React from 'react'
import ReactDOM from 'react-dom'
import * as Broker from 'react-broker'
import App from '../App'


const app = (
  <Broker.Provider>
    <App/>
  </Broker.Provider>
)

Broker.loadInitial().then(
  () => ReactDOM.hydrate(app, document.getElementById('⚛️'))
)

server/render.js

import React from 'react'
import ReactDOMServer from 'react-dom/server'
import express from 'express'
import * as Broker from 'react-broker'
import App from '../App'


export default function createRenderer({
  // These are the Webpack compilation stats returned by Webpack post-run.
  // https://webpack.js.org/api/stats/
  clientStats
}) {
  app = express()

  app.get('*', /* Note 'async' here */ async (req, res, next) => {
    res.set('Content-Type', 'text/html')
    // keeps track of lazy chunks used by the current page
    const chunkCache = Broker.createChunkCache()
    // chunkCache is passed to Broker.Provider as a prop
    const app = (
      <Broker.Provider chunkCache={chunkCache}>
        <App/>
      </Broker.Provider>
    )
    // Preloads the async components and renders the app to a string
    const page = await Broker.loadAll(app, ReactDOMServer.renderToString)
    // You could also do this if you have other requirements in addition to preloading with
    // react-broker
    // await Broker.loadAll(app, ReactDOMServer.renderToStaticMarkup)
    // const page = await ReactDOMServer.renderToString(app)
    
    // Generates <script> and <preload> tags for this page
    const chunks = chunkCache.getChunkScripts(clientStats, {preload: true})

    res.send(`
      <html>
        <head>
          ${chunks.preload}
        </head>
        <body>
          <div id='⚛️'>
            ${app}
          </div>
          ${chunks.scripts}
        </body>
      </html>
    `)
  })

  return app
}