react-router-server

by gabrielbull

gabrielbull / react-router-server

Server Side Rendering library for React Router v4.

445 Stars 22 Forks Last release: almost 3 years ago (4.2.3) MIT License 106 Commits 31 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

React Router Server

Build Status Code Climate npm version Gitter

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

  1. About
  2. Installation
  3. Examples
  4. Usage
  5. API
  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() .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';

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

Loading...
}

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(, 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() .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 (

{this.props.message}
); } }

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';


  

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() .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';

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

Loading...
} )} />

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 (

{this.props.message}
); } }

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 ?  : 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).

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.