I love PayPal’s engineering department. There, I’ve said it. I have followed what Jeff Harrell and the team have been doing ever since I started reading about their wholesale jump into Node.js/Dust.js waters. In fact, their blogs and presentations finally convinced me to push for Node.js in my IBM team as well. I had a pleasure of talking to them at conferences multiple times and I continue to like their overall approach.
PayPal is at its core a no-nonsense enterprise that moved from Java to Node.js. Everything I have seen coming from them had the same pragmatic approach, with concerns you can expect from running Node.js in production – security, i18n, converting a large contingent of Java engineers to Node.js.
More recently, I kept tab on PayPal’s apparent move to from Dust.js to ReactJS. Of course, this time around we learned faster and were already playing with React ourselves (using Dust.js for simpler, content-heavy pages and reserving ReactJS for more dynamic use cases). However, we haven’t really started pushing on ReactJS because I was still looking at how to take advantage of React’s ability to render on the server.
Well, the wait is over. PayPal has won my heart again by releasing a React engine that connects the dots in a way so compatible with what we needed that made me jump with joy. Unlike the version I used for my previous blog post, this one allows server side components to be client-mountable, offering true isomorphic goodness. Finally, a fat-free yogurt that does not taste like paper glue.
Curate and connect
The key importance of PayPal’s engine is in what it brings together. One of the reasons React has attracted so much attention lately is its ability to render into a string on the server, then render to the real DOM on the client using the same code. This is made possible by using NodeJS, which is by now our standard stack (I haven’t written a line of Java code for more than a year, on my honour).
But that is not enough – in order to carry over into the client with the same code, you need ‘soft’ page switching – showing boxes inside other boxes and updating the browser history as these boxes are swapped. This has been brought to us now by another great library – react-router. This module inspired by Ember’s amazing router is quickly becoming ‘the’ router for React applications.
What PayPal did in their engine was connect all these great libraries, then write important glue code to put it all together. It is now possible to mix normal server side templates with pages that start their life on the server, then continue on the client with the state preserved and ready to go as soon as JavaScript is loaded.
Needless to say, this was the solution we were looking for. As far as we are concerned, this will put an end to needless ‘server vs client’ wars, and allow us to have our cake and eat it too. Mmm, cake.
Show us some sample code
OK, let’s get our hands dirty. What many people need when writing applications is a hybrid between a site and an app – the ability to put together a web site that has one or more single-page apps embedded in it. We will build an example site that has two plain ReactJS pages rendered on the server, while the third page is really an SPA taking advantage of react-engine and the ability to go full isomorphic.
We will start by creating a shared layout JSX component to be consumed by all other pages:
var React = require('react');
var Header = require('./header.jsx');
module.exports = React.createClass({
render: function render() {
var bundle;
if (this.props.addBundle)
bundle = <script src='/bundle.js'/>;
return (
<html>
<head>
<meta charSet='utf-8' />
<title>
{this.props.title}
</title>
<link rel="stylesheet" href="/css/styles.css"/>
</head>
<body>
<Header {...this.props}></Header>
<div className="main-content">
{this.props.children}
</div>
</body>
{bundle}
</html>
);
}
});
We extracted common header as a separate component that we required and inlined:
var React = require('react');
module.exports = React.createClass({
displayName: 'header',
render: function render() {
var linkClass = 'header-link';
var linkClassSelected = 'header-link header-selected';
return (
<section className='header' id='header'>
<div className='header-title'>{this.props.title}</div>
<nav className='header-links'>
<ul>
<li className={this.props.selection=='header-home'?linkClassSelected:linkClass} id='header-home'>
<a href='/'>Home</a>
</li>
<li className={this.props.selection=='header-page2'?linkClassSelected:linkClass} id='header-page2'>
<a href='/page2'>Page 2</a>
</li>
<li className={this.props.selection=='header-spa'?linkClassSelected:linkClass} id='header-spa'>
<a href='/spa/section1'>React SPA</a>
</li>
</ul>
</nav>
</section>
);
}
});
The header shows three main pages – ‘Home’, ‘Page2’ and ‘React SPA’. The first two are plain server side pages that are rendered by express and sent to the client as HTML:
var Layout = require('./layout.jsx');
var React = require('react');
module.exports = React.createClass({
render: function render() {
return (
<Layout {...this.props}>
<h2>Home</h2>
<p>An example of a plain server-side ReactJS page.</p>
</Layout>
);
}
});
On to the main course
The third page (‘React SPA’) is where all the fun is. Here, we want to create a single-page app so that when we navigate to it by clicking on its link in the header, all subsequent navigations inside it are client-side. However, true to our isomorphic requirement, we want the initial content of ‘React SPA’ page to be rendered on the server, after which react-router and React component will take over.
To show the potential of this approach, we will build a very useful layout – a page with a left nav containing three links (Section 1, 2 and 3), each showing different content in the content area of the page. If you have seen such a page once, you saw it a million times – this layout is internet’s bread and butter.
We start building our SPA top-down. Our top level ReactJS component will reuse Layout component:
var Layout = require('./layout.jsx');
var React = require('react');
var Nav = require('./nav.jsx');
var Router = require('react-router');
module.exports = React.createClass({
render: function render() {
return (
<Layout {...this.props} addBundle='true'>
<Nav {...this.props}/>
<Router.RouteHandler {...this.props}/>
</Layout>
);
}
});
We have loaded left nav as a Nav component:
var React = require('react');
var Link = require('react-router').Link;
module.exports = React.createClass({
displayName: 'nav',
render: function render() {
var activeClass = 'left-nav-selected';
return (
<section className='left-nav' id='left-nav'>
<div className='left-nav-title'>{this.props.name}</div>;
<nav className='left-nav-links'>
<ul>
<li className='left-nav-link' id='nav-section1'>
<Link to='section1' activeClassName={activeClass}>Section 1</Link>
</li>
<li className='left-nav-link' id='nav-section2'>
<Link to='section2' activeClassName={activeClass}>Section 2</Link>
</li>
<li className='left-nav-link' id='nav-section3'>
<Link to='section3' activeClassName={activeClass}>Section 3</Link>
</li>
</ul>
</nav>
</section>
);
}
});
This looks fairly simple, except for one crucial difference: instead of adding plain ‘a’ tags for links, we used Link components coming from react-router module. They are the key for the magic here – on the server, they will render normal links, but with ‘breadcrumbs’ allowing React router to mount click listeners on them, and cancel normal navigation behaviour. Instead, they will cause React components registered as handlers for these links to be shown. In addition, browser history will be maintained so that back button and address bar works as expected for these ‘soft’ navigations.
Component RouteHandler is responsible for executing the information specified in our route definition:
var Router = require('react-router');
var Route = Router.Route;
var SPA = require('./views/spa.jsx');
var Section1 = require('./views/section1.jsx');
var Section2 = require('./views/section2.jsx');
var Section3 = require('./views/section3.jsx');
var routes = module.exports = (
<Route path='/spa' handler={SPA}>;
<Route name='section1' handler={Section1} />;
<Route name='section2' handler={Section2} />;
<Route name='section3' handler={Section3} />;
<Router.DefaultRoute handler={Section1} />;
</Route>
);
As you can infer, we are not declaring all the routes for our site, just the section for the single-page app (under the ‘/spa’ path). There we have built three subpaths and designated React components as handlers for these routes. When a Link component whose ‘to’ property is equal to the route name is activated, the component designated as handler will be shown.
Server needs to cooperate
In order to get our HTML5 push state enabled router to work, we need server side cooperation. In the olden days when SPAs were using hashes to ensure client side navigation is not causing page reloading, we didn’t need to care about the server because hashes stayed on the client. Those days are over and we want true deep URLs on the client, and we can have them using HTML5 push state support.
However, once we start using true links for everything, we need to tell the server to not try to render pages that belong to the client. We can do this in express like this:
app.get('/', function(req, res) {
res.render('home', {
title: 'React Engine Demo',
name: 'Home',
selection: 'header-home'
});
});
app.get('/page2', function(req, res) {
res.render('page2', {
title: 'React Engine Demo',
name: 'Page 2',
selection: 'header-page2'
});
});
app.get('/spa*', function(req, res) {
res.render(req.url, {
title: 'SPA - React Engine Demo',
name: 'React SPA',
selection: 'header-spa'
});
});
Notice that we have defined controllers for two routes using normal ‘res.render’ approach, but the third one is special. First off, we have instructed express to not try to render any pages under /spa by sending them all to the React router. Notice also that instead of sending normal view names in res.render, we are passing entire URL coming from the request. This particular detail is what makes ‘react-engine’ ingenious – the ability to mix react-router and normal views by looking for the presence of the leading ‘/’ sign.
A bit more boilerplate
Now that we have all these pieces, what else do we need to get this to work? First off, we need the JS file to configure the react router on the client, and start the client side mounting:
var Routes = require('./routes.jsx');
var Client = require('react-engine/lib/client');
// Include all view files. Browserify doesn't do
// this automatically as it can only operate on
// static require statements.
require('./views/**/*.jsx', {glob: true});
// boot options
var options = {
routes: Routes,
// supply a function that can be called
// to resolve the file that was rendered.
viewResolver: function(viewName) {
return require('./views/' + viewName);
}
};
document.addEventListener('DOMContentLoaded', function onLoad() {
Client.boot(options);
});
And to round it all, we need to deliver all this JavaScript, and JSX templates, to the client somehow. There are several ways to approach JavaScript modularization on the client, but since we are using Node.js and sing the isomorphic song, what can be more apt than using Browserify to carry over CommonJS into the client? The following command line will gather the entire dependency tree for index.js into one tidy bundle:
browserify -t reactify -t require-globify public/index.js -o public/bundle.js
If you circle back all the way to Layout.jsx, you will notice that we are including a sole script tag for /bundle.js.
The complete source code for this app is available on GitHub. When we run ‘npm install’ to bring all the dependencies, then ‘npm start’ to run browserify and start express, we get the following:
When we click on header links, they cause full page reload, rendered by express server. However, clicks on the left nav links cause the content of the SPA page to change without a page reload. Meanwhile, the address bar and browser history is dutifully updated, and deep links are available for sharing.
Discussion
You can probably tell that I am very excited about this approach because it finally brings together fast initial rendering and SEO-friendly server-side pages, with full dynamic ability of client side apps. All excitement aside, we need to remember that this is just views – we would need to write more code to add action dispatcher and data stores in order to implement full Flux architecture.
Performance wise, the combined app renders very quickly, but one element sticks out. Bundle.js in its full form is about 800KB of JavaScript, which is a lot. When running the command to minify it, it is trimmed down to 279KB, and when compression is enabled in express, it goes further down to 62.8KB to send down the wire. We should bear in mind that this is ALL JavaScript we need – ReactJS, as well as our own components. It should also be noted that this JavaScript is loaded asynchronously and that we are sending content from the server already – we will not see a white page while script is being downloaded and parsed.
In a more complex application, we would probably want to segregate JavaScript into more than one bundle so that we can load code in chunks as needed. Luckily, react-router already addressed this.
The app is deployed on Bluemix – you can access it at http://react-engine-demo.mybluemix.net. Try it out, play with the source code and let me know what you think.
Great job, PayPal! As for me, I am completely sold on ReactJS for most real world applications. We will be using this approach in our current project from now on.
© Dejan Glozic, 2015
