Skip to content

a composite render engine for universal (isomorphic) express apps to render both plain react views and react-router views

License

Notifications You must be signed in to change notification settings

easilyBaffled/react-engine

 
 

Repository files navigation

react-engine

Build Status

What is react-engine?

  • a react render engine for Universal (previously Isomorphic) JavaScript apps written with express
  • renders both plain react views and react-router views
  • enables server rendered views to be client mountable

Install

  npm install react-engine --save

Usage On Server Side

Setup in an Express app
    var Express = require('express');
    var ReactEngine = require('react-engine');

    var app = Express();

    // create an engine instance
    var engine = ReactEngine.server.create({
      /*
        see the complete server options spec here:
        https://github.com/paypal/react-engine#server-options-spec
      */
    });

    // set the engine
    app.engine('.jsx', engine);

    // set the view directory
    app.set('views', __dirname + '/views');

    // set jsx or js as the view engine
    // (without this you would need to supply the extension to res.render())
    // ex: res.render('index.jsx') instead of just res.render('index').
    app.set('view engine', 'jsx');

    // finally, set the custom view
    app.set('view', require('react-engine/lib/expressView'));
Setup in a KrakenJS app's config.json
  {
    "express": {
        "view engine": "jsx",
        "view": "require:react-engine/lib/expressView",
    },
    "view engines": {
        "jsx": {
            "module": "react-engine/lib/server",
            "renderer": {
              "method": "create",
                "arguments": [{
                        /*
                          see the complete server options spec here:
                          https://github.com/paypal/react-engine#server-options-spec
                        */
                }]
            }
        }
    }
  }
Server options spec

Pass in an optional JavaScript object as options to the react-engine's server engine create method. The options object can contain properties from react router's create configuration object.

Additionally, it can contain the following optional properties,

  • performanceCollector: - to collects perf stats
  • routesFilePath: - path for the file that contains the react router routes. react-engine uses this behind the scenes to reload the routes file in cases where express's app property view cache is false, this way you don't need to restart the server every time a change is made in the view files or routes file.
Rendering views on server side
var data = {}; // your data model

// for a simple react view rendering
res.render(viewName, data);

// for react-router rendering
// pass in the `url` and react-engine
// will run the react-router behind the scenes.
res.render(req.url, data);

Usage On Client Side (Mounting)

// assuming we use `browserify`
var client = require('react-engine').client;

// finally, boot whenever your app is ready
// example:
document.addEventListener('DOMContentLoaded', function onLoad() {

  // `onBoot` - Function (optional)
  // returns data that was used
  // during rendering as the first argument
  client.boot(/* client options object */, function onBoot(data) {

  });
};

// if the data is needed before booting on
// client, call `data` function anytime to get it.
// example:
var data = client.data();
Client options spec

Pass in a JavaScript object as options to the react-engine's client boot function. The options object can contain properties from react router's create configuration object.

Additionally, it should contain the following required property,

  • viewResolver : - a function that react-engine needs to resolve the view file. an example of the viewResolver can be found here.

Yeoman Generator

There is a Yeoman generator available to create a new express or KrakenJS application which uses react-engine: generator-react-engine.

Performance Profiling

Pass in a function to the performanceCollector property to collect the stats object for every render.

stats

The object that contains the stats info for each render by react-engine. It has the below properties.

  • name - Name of the template or the url in case of react router rendering.
  • startTime - The start time of render.
  • endTime - The completion time of render.
  • duration - The duration taken to render (in milliseconds).
// example
function collector(stats) {
  console.log(stats);
}

var engine = require('react-engine').server.create({
  reactRoutes: './routes.jsx'
  performanceCollector: collector
});

Notes

  • On the client side, the state is exposed on the window object's property __REACT_ENGINE__
  • When Express's view cache app property is false (mostly in non-production environments), views are automatically reloaded before render. So there is no need to restart the server for seeing the changes.
  • You can use js as the engine if you decide not to write your react views in jsx.
  • Blog on react-engine

Migration from 1.x to 2.x

2.x version of react-engine brought in a major api change. Basically it affects the property names of the object that gets passed in during the engine creation on the server side and also how routes definition is passed into react-engine.

In v2.x, routes need to be explicitly required and passed in to the engine creation method. Also, any react-router known properties can be passed in.

An example engine creation can be found here.

License

Apache Software License v2.0

About

a composite render engine for universal (isomorphic) express apps to render both plain react views and react-router views

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 99.3%
  • Shell 0.7%