Server Side Rendering

Install

npm install @loadable/server && npm install --save-dev @loadable/babel-plugin @loadable/webpack-plugin
# or using yarn
yarn add @loadable/server && yarn add --dev @loadable/babel-plugin @loadable/webpack-plugin

Guide

1. Install `@loadable/babel-plugin`

.babelrc

{
  "plugins": ["@loadable/babel-plugin"]
}

2. Install `@loadable/webpack-plugin`

webpack.config.js

const LoadablePlugin = require('@loadable/webpack-plugin')
module.exports = {
  // ...
  plugins: [new LoadablePlugin()],
}

3. Setup `ChunkExtractor` server-side

import { ChunkExtractor } from '@loadable/server'
// This is the stats file generated by webpack loadable plugin
const statsFile = path.resolve('../dist/loadable-stats.json')
// We create an extractor from the statsFile
const extractor = new ChunkExtractor({ statsFile })
// Wrap your application using "collectChunks"
const jsx = extractor.collectChunks(<YourApp />)
// Render your application
const html = renderToString(jsx)
// You can now collect your script tags
const scriptTags = extractor.getScriptTags() // or extractor.getScriptElements();
// You can also collect your "preload/prefetch" links
const linkTags = extractor.getLinkTags() // or extractor.getLinkElements();
// And you can even collect your style tags (if you use "mini-css-extract-plugin")
const styleTags = extractor.getStyleTags() // or extractor.getStyleElements();

4. Add `loadableReady` client-side

Loadable components loads all your scripts asynchronously to ensure optimal performances. All scripts are loaded in parallel, so you have to wait for them to be ready using loadableReady.

import { loadableReady } from '@loadable/component'
loadableReady(() => {
  const root = document.getElementById('main')
  hydrate(<App />, root)
})

🚀 Checkout the complete example in this repository

Collecting chunks

The basic API goes as follows:

import { renderToString } from 'react-dom/server'
import { ChunkExtractor } from '@loadable/server'
const statsFile = path.resolve('../dist/loadable-stats.json')
const extractor = new ChunkExtractor({ statsFile })
const html = renderToString(extractor.collectChunks(<YourApp />))
const scriptTags = extractor.getScriptTags() // or extractor.getScriptElements();

The collectChunks method wraps your element in a provider. Optionally you can use the ChunkExtractorManager provider directly, instead of this method. Just make sure not to use it on the client-side.

import { renderToString } from 'react-dom/server'
import { ChunkExtractor, ChunkExtractorManager } from '@loadable/server'
const statsFile = path.resolve('../dist/loadable-stats.json')
const extractor = new ChunkExtractor({ statsFile })
const html = renderToString(
  <ChunkExtractorManager extractor={extractor}>
    <YourApp />
  </ChunkExtractorManager>,
)
const scriptTags = extractor.getScriptTags() // or extractor.getScriptElements();

The extractor.getScriptTags() returns a string of multiple <script> tags marked as "async". You have to wait for them to be ready using loadableReady.

Alternatively the ChunkExtractor also has a getScriptElements() method that returns an array of React elements.

Streaming rendering

Loadable is compatible with streaming rendering, if you use it you have to include script when the stream is complete.

import { renderToNodeStream } from 'react-dom/server'
import { ChunkExtractor } from '@loadable/server'
// if you're using express.js, you'd have access to the response object "res"
// typically you'd want to write some preliminary HTML, since React doesn't handle this
res.write('<html><head><title>Test</title></head><body>')
const statsFile = path.resolve('../dist/loadable-stats.json')
const chunkExtractor = new ChunkExtractor({ statsFile })
const jsx = chunkExtractor.collectChunks(<YourApp />)
const stream = renderToNodeStream(jsx)
// you'd then pipe the stream into the response object until it's done
stream.pipe(
  res,
  { end: false },
)
// and finalize the response with closing HTML
stream.on('end', () =>
  res.end(`${chunkExtractor.getScriptTags()}</body></html>`),
)

Streaming rendering is not compatible with prefetch <link> tags.

Prefetching

Webpack prefetching is supported out of the box by Loadable. <link rel="preload"> and <link rel="prefetch"> can be added directly server-side to improve performances.

import path from 'path'
import { ChunkExtractor, ChunkExtractorManager } from '@loadable/server'
const statsFile = path.resolve('../dist/loadable-stats.json')
const extractor = new ChunkExtractor({ statsFile })
const jsx = extractor.collectChunks(<YourApp />)
const html = renderToString(jsx)
const linkTags = extractor.getLinkTags() // or chunkExtractor.getLinkElements();
const html = `<html>
  <head>${linkTags}</head>
  <body>
    <div id="root">${html}</div>
  </body>
</html>`

It only works with renderToString API. Since <link> must be added in the <head>, you can't do it using renderToNodeStream.

CSS

Extracted CSS using plugins like "mini-css-extract-plugin" are automatically collected, you can get them using getStyleTags or getStyleElements.

import { renderToString } from 'react-dom/server'
import { ChunkExtractor } from '@loadable/server'
const statsFile = path.resolve('../dist/loadable-stats.json')
const extractor = new ChunkExtractor({ statsFile })
const html = renderToString(extractor.collectChunks(<YourApp />))
const styleTags = extractor.getStyleTags() // or extractor.getStyleElements();

Disable SSR on a specific loadable

Disable SSR on a specific loadable component with ssr: false:

import loadable from '@loadable/component'
// This dynamic import will not be processed server-side
const Other = loadable(() => import('./Other'), { ssr: false })

Override `stats.publicPath` at runtime

To override stats.publicPath at runtime, pass in a custom publicPath to the ChunkExtractor constructor:

import { ChunkExtractor } from '@loadable/server'
const statsFile = path.resolve('../dist/loadable-stats.json')
const extractor = new ChunkExtractor({
  statsFile,
  publicPath: 'https://cdn.example.org/v1.1.0/',
})

Loadable Components