gabrielbull
](https://gitter.im/gabrielbull/react-router-server?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge){kind=icon}
Server Side Rendering library for React Router v4.
Help wanted!
If anyone is interested in taking over this project please let me know.
Table Of Content
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 git@github.com:gabrielbull/react-router-server-complex-example.git
npm install
npm startUsage
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).