Help wanted!

If anyone is interested in taking over this project please let me know.

Table Of Content

1. About
2. Installation
3. Examples
   • Example
4. Usage
   • Server Side Rendering
   • Code Splitting
   • Fetch State
   • Usage with Webpack
   • Usage with React Router
   • Usage with Redux
5. API
   • extractModules
   • fetchState
   • withDone
   • Module
   • preload
   • renderToString
   • ServerStateProvider
6. Contributing
7. License

About

This library allows to fetch states for your components on the server side and mount them on the client side.

It also allows to do code splitting by providing a component that can be used to load modules splitted by Webpack 2.

Installation

npm install react-router-server --save

Examples

Example

A working example using Webpack bundle and preloading is provided here. To try for yourself, you can clone it and run it. This will provide a server accessible at http://localhost:3000.

git clone [email protected]:gabrielbull/react-router-server-complex-example.git
npm install
npm start

Usage

Server Side rendering

To render an app that has code splitting or state fetching, you need to load the modules and states required by your app before rendering. react-dom/server does not offer a function to do that, but you can use the renderToString function provided by this library. This function will return a promise that will return the rendered app once the modules and states are loaded.

import { renderToString } from 'react-router-server';
import App from './path/to/app';

renderToString(<App/>)
  .then(({ html }) => {
    // send html to client side
  });

Code Splitting

The code splitting consist of a component that you can use to load modules splitted by Webpack 2. It also allows you to get information on the modules required to render a page so that you can preload the modules before displaying the page on the client side.

To use code splitting, you will need to import the Module component and provide the System.import call inside the module property of that component. Then, you need to defined a callback function as the children of the component.

import { Module } from 'react-router-server';

<Module module={() => System.import('./Foo')}>
  {module => module ? <module.default/> : <div>Loading...</div>}
</Module>

To preload the modules on the client side, you can use the preload method and pass the modules from the server into that method.

In the following example, __INITIAL_MODULES__ would be provided by the server and rendered in the HTML document as a global variable.

import { preload } from 'react-router-server';
import { render } from 'react-dom';
import App from './path/to/app';

preload(__INITIAL_MODULES__).then(() => render(<App/>, document.getElementById('#my-app')));

You can get the modules from the renderToString function on the server side and extract them from your webpack stats by using the extractModules method. For more information on usage with webpack, check the usage with webpack part of this read me.

import { renderToString, extractModules } from 'react-router-server';
import App from './path/to/app';
import stats from './path/to/stats';

renderToString(<App/>)
  .then(({ html, modules }) => {
    modules = extractModules(modules, stats);
    // send html and modules to client side
  });

To be able to use System.import calls on the server side, you will need to install the babel-plugin-system-import-transformer plugin.

Fetch State

On the server side, you will often need to fetch data before rendering your component and then pass that data to the client side so that the components are in sync.

To fetch data for your components, use the fetchState decorator provided by this library. The fetchState decorator takes two arguments, mapStateToProps and mapActionsToProps. mapStateToProps allows you to map the state to the props of your component while mapActionsToProps allows you to map the done action to the props of your component.

import * as React from 'react';
import { fetchState } from 'react-router-server';

@fetchState(
  state => ({ message: state.message }),
  actions => ({ done: actions.done })
)
class MyComponent extends React.Component {
  componentWillMount() {
    if (!this.props.message) {
      setTimeout(() => {
        this.props.done({ message: 'Hello world!' });
      }, 10);
    }
  }

  render() {
    return (
      <div>{this.props.message}</div>
    );
  }
}

To pass that state from the server to the client, you need to wrap the client app with the ServerStateProvider and pass the state from the server into that component's state property.

In the following example, __INITIAL_STATE__ would be provided by the server and rendered in the HTML document as a global variable.

import { ServerStateProvider } from 'react-router-server';
import App from './path/to/app';

<ServerStateProvider state={__INITIAL_STATE__}>
  <App/>
</ServerStateProvider>

You can get the state from the renderToString function on the server side.

import { renderToString } from 'react-router-server';
import App from './path/to/app';

renderToString(<App/>)
  .then(({ html, state }) => {
    // send html and state to client side
  });

Usage with Webpack

You can extract the required modules per requests when running your server to pass them to the client side. This allows you to preload your modules before running the client side app. To do so, you need to get the stats from Webpack.

There are many ways to do this, but we recommend using the stats-webpack-plugin. Here's a code sample that you can add to your webpack config's plugins section. This will create a stats.json file that you can use to extract the required modules for your app.

[
  new StatsPlugin('stats.json', {
    chunkModules: true,
    exclude: [/node_modules/]
  })
]

To extract the modules, you can use the extractModules function and pass the modules provided by the renderToString as well as the stats generated by webpack. See the code splitting usage part of this documentation to learn more on code splitting.

To be able to use System.import calls on the server side, you will need to install the babel-plugin-system-import-transformer plugin.

Usage with React Router

To use with React Router v4, you can pass the Module component to the Route component of React Router.

import { Route } from 'react-router';
import { Module } from 'react-router-server';

<Route
  exact
  path="/"
  render={matchProps => (
    <Module module={() => System.import('./Foo')}>
      {module => module ? <module.default {...matchProps}/> : <div>Loading...</div>}
    </Module>
  )}
/>

Usage with Redux

If you are rehydrating state with redux instead of using ServerStateProvider, all you need is access to the done action so the server can wait for async stuff to complete. In that case, you can use the withDone decorator, which is a shorthand for fetchState(null, ({ done }) => ({ done })).

import * as React from 'react';
import { connect } from 'react-redux';
import { withDone } from 'react-router-server';
import { setMessage } from './actions';

@withDone
@connect(state => state.message, { setMessage })
class MyComponent extends React.Component {
  componentWillMount() {
    // using async actions
    const { setMessage, done } = this.props;
    setMessage('Hello world').then(done, done);
  }

  render() {
    return (
      <div>{this.props.message}</div>
    );
  }
}

For more details on usage with redux, check this boilerplate.

API

extractModules

extractModules(modules, stats)

modules: modules provided by the renderToString method.

stats: stats generated by webpack.

fetchState

fetchState(mapStateToProps, mapActionsToProps)

mapStateToProps(state): function to map the state provided by the done action to props in your component;

mapActionsToProps(actions): function to map the actions to props in your component; Currently, only the done action exists and is used when you are finished fetching props.

withDone

Shorthand for fetchState(null, ({ done }) => ({ done }))

Module

The Module component allows to do code splitting. The Module component takes these propeties:

module: a function that returns a System.import call. E.G. () => System.import('./Foo')

children: a function. E.G. {module => module ? <module.default/> : null}

preload

preload(modules)

modules: array of modules passed by the server side to the client side for preloading.

renderToString

Async version of ReactDOM.renderToString.

renderToString(element)

element: The element to render

Returns an object ({ html, state, modules }) with:

html: the rendered HTML

state: the app state provided by fetch state

modules: the app modules provided by code splitting

ServerStateProvider

The ServerStateProvider component is used for providing the server state to the client side. Provided by the state prop.

Contributing

Everyone is welcome to contribute and add more components/documentation whilst following the contributing guidelines.

License

React Router Server is licensed under The MIT License (MIT).