React-SSR-Starter

This package is meant to help with the creation of an isomorphic React + Redux application.

Philosophy

By using this package you agree several choices made during its implementation, like:

• the use of Redux as state container
• the use of the Thunk middleware to deal with asynchronous actions
• the choice of a state-connected routing
• the use of Express JS as web framework
• the use of Handlebars as server template engine
• many other implementation details

The reason why all these dependencies were put into a single package is to facilitate the decomposition of a complex web application into many small applications without facing the same problems each time. Each decision about putting things inside or leaving outside the module is a trade-off between flexibility of use and reduction of duplication.

Overview

The package includes two main parts: a Client and a Server classes. You instantiate a server object on your Node.js server and a client object on the client.

The Server is reponsible to serve full rendered pages by prefetching any required data (see Component requirements section).

The Client is responsible to boostrap and render the React client application.

Rendering and routing are managed isomorphically in fact you need to pass a common routing configuration to both client and server, see Server configuration and Client configuration for more details.

Install and usage

yarn add react-ssr-starter

On the server:

import Server from 'react-ssr-starter/Server';

 // see the "Server configuration" section
const config = { ... };

const server = new Server(config);
server.start(() => console.log(`Server listening on port ${config.port}`));

On the client:

import Client from 'react-ssr-starter/Client';

// see the "Client configuration" section
const config = { ... };

const client = new Client(config);
client.render(document.getElementById('root'));

Server configuration

The Server class constructor accepts a single configuration object parameter with the following properties:

port ( default: 8080 )

The port that will be used by the web server.

template ( default: null )

A path to an handlebars template that will be used to render the page on the server.

layoutUrl ( default: null)

An URL to an handlebars layout. This field can be a string containing the URL or a function returning an URL. The function will be invoked by passing the Express request object. It can be useful if the URL the layout depends on the request input (Ex. the user-agent header).

The only required placeholder for the layout is {{content}} which will be replaced by the app content. Any other placeholder present will have chance to be replaced by the use of the layoutVariables property.

layoutVariables ( default: {} )

An object with properties that will be used to match the layout or template placeholders. This field can also be a function returning an object.

headersToForward ( default: ['user-agent'] )

An array of header names to forward in the HTTP request of the remote layout.

middlewares ( default: [] )

An array of Express middlewares. They will be registered after the Express.static middleware and before the main application routing middleware.

rootReducer ( default: {} )

The already combined Redux reducers object.

routes ( default: [] )

An array of objects with path and component properties.

Example:

[{
  path: '/',
  component: Home 
}]

preloadState ( default: null )

A function returning the initial redux state.

serveStatic ( default: false )

Enable the Express.static middleware activating the static file serving. The folder served is the one specified by the staticFolder parameter.

staticFolder ( default: 'public' )

The folder that will be used by the Express.static middleware (if enabled by the serveStatic parameter) to search static content.

staticPath ( default: '/public' )

The path that will be used by Express.static middleware (if enambled by the serveStatic parameter) to expose staic content.

middlewares ( default: [] )

An array of express middlewares to be registered.

inject ( default: null )

This is a thunk specific argument. It allow to inject extra argument into every action creator along with the dispatch and the getState arguments.

onError (default: see description)

This is a callback to be executed in case of error during the handling of the request. Its default value is a function that print the error to the console and return an 500 status code.

This function take the same parameters of an Express middleware: req, res, err. If you override the default function it's your responsibility to send a response to the client otherwise the request will stay hanging.

Client configuration

The Client class contructor accept a single configuration object with the following properties:

routes ( default: null)

This has to be the same object passed to server (see the server config)

rootReducer ( default: null )

This has to be the same object passed to server (see the server config)

initialState ( default: null )

This field deserve special attention because it's the point of contact between client and server data. The client has to fill this field with the state coming from the server. See the example app to more details.

inject ( default: null )

The Redux-Thunk injections.

middlewares ( default: [] )

An array of Redux middleware to be registered.

Component requirements

Components that requires initial data to be rendered can speify a static property requirements like in the following example:

class Planets {
  ...
}

Planets.requirements = [
    fetchPlanets,
    ['/planets/:id', (params) => fetchPlanetDetails(params.id) ]
  ]

requirements is an array and each item inside it can be a plain Redux Action like fetchPlanets or a bit more complicated expression like the second one in the example above. This expression means that the component Planet requires also the execution of the action fetchPlanetDetails if the routes match the /planets/:id pattern. As you can see you are able to access to route parameters.

FAQ

What's the difference between the template and layoutUrl parameters?

todo

Why there are two parameters staticFolder and staticPath?

todo

What do you mean with state-connected routing?

todo

How to contribute

All the main code is inside the /src folder.

The /example folder contains an example application so that you can easly experiment or add new functionality.

To make development more confortable you can link the react-ssr-starter package instead of installing it directly from npm.

Build the react-ssr-starter package locally

cd react-ssr-starter
yarn
yarn build

Link the package

yarn link

Launch the example app using the local built package

cd example
yarn link react-ssr-starter
yarn
yarn dev