A Climate for Change

The creation of the World Wide Web is attributed to Tim Berners Lee, who, while working for a nuclear research company on a project known as “Enquire” experimented with the concept of hyperlinks. In 1989, Tim applied the concept of hyperlinks and put a proposal together for a centralized database that contained links to other documents. Over the course of time, this database has morphed into something much larger and has had a huge impact on our daily lives (e.g., through social media) and business (ecommerce). We are all teenagers stuck in a virtual mall. The variety of content and shopping options empowers us to make informed decisions and purchases. Businesses realize the plethora of choices we have as consumers, and are greatly concerned with ensuring that we can find and view their content and products, with the ultimate goal of achieving conversions (buying stuff)—so much so that there are search engine optimization (SEO) experts whose only job is to make content and products appear higher in search results. However, that is not where the battle for conversions ends. Once consumers can find the products, the pages must load quickly and be responsive to user interactions, or else the businesses might lose the consumers to competitors. This is where we, engineers, enter the picture, and we have our own set of concerns in addition to the business’s concerns.

Engineering Concerns

As engineers, we have a number of concerns, but for the most part these concerns fall into the main categories of maintainability and efficiency. That is not to say that we do not consider business concerns when weighing technical decisions. As a matter of fact, good engineers do exactly the opposite: they find the optimal engineering solution by contemplating the short- and long-term pros and cons of each possibility within the context of the business problem at hand.

Available Architectures

Taking into account the primary business use case, an ecommerce application, we are going to examine a couple of different architectures within the context of history. Before we take a look at the architectures, we should first identify some key acceptance criteria, so we can fairly evaluate the different architectures. In order of importance:

1. The application should be able to be indexed by search engines.

2. The application’s first page load should be optimized—i.e., the critical rendering path should be part of the initial response.

3. The application should be responsive to user interactions (e.g., optimized page transitions).

These business criteria will also be weighed against the primary engineering concerns, maintainability and efficiency, throughout the evaluation process.

Classic web application

As mentioned in the previous section, the Web was designed and created to share information. Since the premise of the World Wide Web was the work done for the Enquire project, it is no surprise that when the Web first started, web pages were simply multipage text documents that linked to other text documents. In the early 1990s, most of the Web was rendered as complete HTML pages. The mechanisms that supported (and continue to support) it are HTML, URIs, and HTTP. HTML (Hypertext Markup Language) is the specification for the markup that is translated into the document object model by browsers when the markup is parsed. The URI (uniform resource identifier) is the name that identifies a resource; i.e., the name of the server that should respond to a request. HTTP (Hypertext Transfer Protocol) is the transport protocol that connects everything together. These three mechanisms power the Internet and shaped the architecture of the classic web application.

A classic web application is one in which all the markup—or, at a minimum, the critical rendering path markup—is rendered by the server using a server-side language such as PHP, Ruby, Java, and so on (Figure 1-1). Then JavaScript is initialized when the browser parses the document, enriching the user experience.

Figure 1-1. Classic web application flow

In a nutshell, that is the classic web application architecture. Let’s see how it stacks up against our acceptance criteria and engineering concerns.

Firstly, it is easily indexed by search engines because all of the content is available when the crawlers traverse the application, so consumers can find the application’s content. Secondly, the page load is optimized because the critical rendering path markup is rendered by the server, which improves the perceived rendering speed, so users are more likely not to bounce from the application. However, two out of three is as good as it gets for the classic web application.

Note

What do we mean by “perceived” rendering speed? In High Performance Browser Networking, Grigorik explains it this way as: “Time is measured objectively but perceived subjectively, and experiences can be engineered to improve perceived performance.”

In the classic web application, navigation and transfer of data work as the Web was originally designed. The browser requests, receives, and parses a full document response when a user navigates to a new page or submits form data, even if only some of the page information has changed. This is extremely effective at meeting the first two criteria, but the setup and teardown of this full-page lifecycle are extremely costly, so it is a suboptimal solution in terms of responsiveness. Since we are privileged enough to live in the time of Ajax, we already know that there is a more efficient method than a full page reload—but it comes at a cost, which we will explore in the next section. However, before we transition to the next section we should take a look at Ajax within the context of the classic web application architecture.

The Ajax era

The XMLHttpRequest object is the spark that ignited the web platform fire. However, its integration into classic web applications has been less impressive. This was not due to the design or technology itself, but rather to the inexperience of those who integrated the technology into classic web applications. In most cases they were designers who began to specialize in the view layer. I myself was an administrative assistant turned designer and developer. I was abysmal at both. Needless to say, I wreaked havoc on my share of applications over the years (but I see this as my contribution to the evolution of a platform!). Unfortunately, all the applications I touched and all the other applications that those of us without the proper training and guidance touched suffered during this evolutionary period. The applications suffered because processes were duplicated and concerns were muddled. A good example that highlights these issues is a related products carousel (Figure 1-2).

Figure 1-2. Example of a product carousel

A (related) products carousel paginates through products. Sometimes all the products are preloaded, and in other cases there are too many to preload. In those cases a network request is made to paginate to the next set of products. Refreshing the entire page is extremely inefficient, so the typical solution is to use Ajax to fetch the product page sets when paginating. The next optimization would be to only get the data required to render the page set, which would require duplicating templates, models, assets, and rendering on the client (Figure 1-3). This also necessitates more unit tests. This is a very simple example, but if you take the concept and extrapolate it over a large application, it makes the application difficult to follow and maintain—one cannot easily derive how an application ended up in a given state. Additionally, the duplication is a waste of resources and it opens up an application to the possibility of bugs being introduced across two UI code bases when a feature is added or modified.

Figure 1-3. Classic web application with Ajax flow

This division and replication of the UI/View layer, enabled by Ajax and coupled with the best of intentions, is what turned seemingly well-constructed applications into brittle, regression-prone piles of rubble and frustrated numerous engineers. Fortunately, frustrated engineers are usually the most innovative. It was this frustration-fueled innovation, combined with solid engineering skills, that led us to the next application architecture.

Single-page web application

Everything moves in cycles. When the Web began it was a thin client, and likely the inspiration for the Sun Microsystems NetWork Terminal (NeWT). But by 2011 web applications had started to eschew the thin client model, and transition to a fat client model like their operating system counterparts had done long ago. The monolith had surfaced. It was the dawn of the single-page application (SPA) architecture.

The SPA eliminates the issues that plague classic web applications by shifting the responsibility of rendering entirely to the client. This model separates application logic from data retrieval, consolidates UI code to a single language and runtime, and significantly reduces the impact on the servers (Figure 1-4).

Figure 1-4. Single-page application flow

It accomplishes this reduction because the server sends a payload of assets, JavaScript, and templates to the client. From there, the client takes over only fetching the data it needs to render pages/views. This behavior significantly improves the rendering of pages because it does not require the overhead of fetching and parsing an entire document when a user requests a new page or submits data. In addition to the performance gains, this model also solves the engineering concerns that Ajax introduced to the classic web application.

Going back to the product carousel example, the first page of the (related) products carousel was rendered by the application server. Upon pagination, subsequent requests were then rendered by the client. The blurring of the lines of responsibility and duplication of efforts evidenced here are the primary problems of the classic web application in the modern web platform. These issues do not exist in an SPA.

In an SPA there is a clear line of separation between the responsibilities of the server and client. The API server responds to data requests, the application server supplies the static resources, and the client runs the show. In the case of the products carousel, an empty document that contains a payload of JavaScript and template resources would be sent by the application server to the browser. The client application would then initialize in the browser and request the data required to render the view that contains the products carousel. After receiving the data, the client application would render the first set of items for the carousel. Upon pagination, the data fetching and rendering lifecycle would repeat, following the same code path. This is an outstanding engineering solution. Unfortunately, it is not always the best user experience.

In an SPA the initial page load can appear extremely sluggish to the end users, because they have to wait for the data to be fetched before the page can be rendered. So instead of seeing content immediately when the pages loads, they get an animated loading indicator, at best. A common approach to mitigate this delayed rendering is to serve the data for the initial page. However, this requires application server logic, so it begins to blur the lines of responsibility once again and adds another layer of code to maintain.

The next issue SPAs face is both a user experience and a business issue. They are not SEO-friendly by default, which means that users will not be able to find an application’s content by searching. The problem stems from the fact that SPAs leverage the hash fragment for routing. Before we examine why this impacts SEO, let’s take a look at the mechanics of SPA routing.

SPAs rely on the fragment to map faux URI paths to a route handler that renders a view in response. For example, in a classic web application an “about us” page URI might look like http://domain.com/about, but in an SPA it would look like http://domain.com/#about. The SPA uses a hash mark and a fragment identifier at the end of the URL. The reason the SPA router uses the fragment is because the browser does not make a network request when the fragment changes, unlike when there are changes to the URI. This is important because the whole premise of the SPA is that it only requests the data required to render a view/page, as opposed to fetching and parsing a new document for each page.

SPA fragments are not SEO-compatible because hash fragments are never sent to the server as part of the HTTP request (per the specification). As far as a web crawler is concerned, http://domain.com/#about and http://domain.com/#faqs are the same page. Fortunately, Google has implemented a work around to provide SEO support for fragments: the hashbang (#!).

Note

Most SPA libraries now support the History API, and recently Google crawlers have gotten better at indexing JavaScript applications—previously, JavaScript was not even executed by web crawlers.

The basic premise is to replace the # in an SPA fragment’s route with a #!, so http://domain.com/#about would become http://domain.com/#!about. This allows the Google crawler to identify content to be indexed from simple anchors.

Note

An anchor tag is used to create links to the content within the body of a document.

The crawler then transforms the links into fully qualified URI versions, so http://domain.com/#!about becomes http://domain.com/?query&_escaped_fragment=about. At that point it is the responsibility of the server that hosts the SPA to serve a snapshot of the HTML that represents http://domain.com/#!about to the crawler in response to the URI http://domain.com/?query&_escaped_fragment=about. Figure 1-5 illustrates this process.

Figure 1-5. Crawler flow to index an SPA URI

At this point, the value proposition of the SPA begins to decline even more. From an engineering perspective, one is left with two options:

1. Spin up the server with a headless browser, such as PhantomJS, to run the SPA on the server to handle crawler requests.

2. Outsource the problem to a third-party provider, such as BromBone.

Both potential SEO fixes come at a cost, and this is in addition to the suboptimal first page rendering mentioned earlier. Fortunately, engineers love to solve problems. So just as the SPA was an improvement over the classic web application, so was born the next architecture, isomorphic JavaScript.

Sharing Templates

In order to achieve faster (perceived) performance and proper search engine indexing, we want to be able to render any view on the server as well as the client. On the client, template rendering is as simple as evaluating a template and attaching the output to a DOM element. On the server, the same template is rendered as a string and returned in the response. The tricky part of isomorphic view rendering is that the client has to pick up wherever the server left off. This is often called the client/server transition; that is, the client should properly transition and not “destroy” the DOM generated by the server after the application is loaded in the browser. The server needs to “dehydrate” the state by sending it to the client, and the client will “rehydrate” (or reanimate) the view and initialize it to the same state it was in on the server.

Example 2-1 illustrates a typical response from the server, which has the rendered markup in the body of the page and the serialized state within a <script> tag. The server puts the serialized state in the rendered view, and the client will deserialize the state and attach it to the prerendered markup.

<html>
  <body>
    <div>[[server_side_rendered_markup]]</div>
    <script>window.__state__=[[serialized_state]<]/script>
    ...
  </body>
</html>

Sharing View Logic

Template helpers are objects, like numbers, strings, or hash objects, and are typically easy to share. For sharing formatting like dates, many formatting libraries work both on the server and on the client. Moment.js, for example, can parse, validate, manipulate, and display dates in JavaScript both on the server and on the client. URL formatting, on the other hand, requires prepending the host and port to the path, whereas on the client we can simply use the relative URL.

Isomorphic APIs

In an isomorphic real-time application, the client interacts with its local data cache similarly to how the server interacts with the backing database. The server code is executing a statement against a database. That same statement is executed on the client to fetch data out of an in-memory cache using the same database API. This symmetry between client and server APIs is often referred to as isomorphic APIs. Isomorphic APIs relieve the developer from having to juggle different strategies for accessing data. But more importantly, isomorphic APIs make it possible to run an application’s core business logic (especially across the model layer) and rendering logic on both the client and the server. Having an isomorphic API for accessing data allows us to share server code and the client application code for validating the updates to the data, accessing and storing the data, and transforming data. By using a consistent API, we remove the friction of having to write different variations of doing the same thing, having to test it in different ways, and having to update code twice when we need to change the data model. Isomorphic APIs are about being intelligent by following the DRY (Don’t Repeat Yourself) principle.

Bidirectional Data Synchronization

Another important aspect of real-time applications is the synchronization between the server’s database and the client’s local cache. Updates to the server from a client should be updated in the client’s local cache, and vice versa. Meteor.js is a good example of a real-time isomorphic framework that lets developers write JavaScript that runs on both the server and the client. Meteor has a “Database Everywhere” principle. Both the client and the server in Meteor use the same isomorphic APIs to access the database. Meteor also uses database abstractions, like minimongo, on the client and an observable collection over a DDP (dynamic data protocol) to keep the data in sync between the server and the client. It is the client database (not the server database) that drives the UI. The client database does lazy data synchronizing to keep the server database up to date. This allows the client to be offline and to still process user data changes locally. A write on the client can optionally be a speculative write to the client’s local cache before hearing a confirmation back from the server. Meteor has a built-in latency compensation mechanism for refreshing the speculative cache if any writes to the server’s database fail or are overwritten by another client.

Client Simulation on the Server

Taking isomorphic JavaScript to the extreme, real-time isomorphic applications may run separate processes on the server for each client session. This allows the server to look at the data that the application loads and proactively send data to the client, essentially simulating the UI on the server. This technique has been famously used by the Asana application. Asana is a collaborative project management tool built on an in-house, closed-source framework called Luna. Luna is tailored for writing real-time web applications and is similar to Meteor.js in providing a common isomorphic API for accessing data on the client and the server. However, what makes Luna unique is that it runs a complete copy of the application on the server. Luna simulates the client on the server by executing the same JavaScript code on the server that is running in the client. As a user clicks around in the Asana UI, the JavaScript events in the client are synchronized with the server. The server maintains an exact copy of the user state by executing all the views and events, but simply throws away the HTML.

A recent post on Asana’s engineering blog indicates that Asana is moving away from this kind of client/server simulation, though. Performance is an issue, especially when the server has to simulate the UI in multiple states so that it can anticipate and preload data on the client for immediate availability. The post also cites versioning as an issue for mobile clients that may run older versions of the code, which makes simulation tricky since the client and the server are not running exactly the same code.

Installing from Source

This section outlines how to install Node from source. I highly recommend using one of the installers or a package manager, but if you are one of those rare birds who enjoy installing software from source, then this is the section for you. Otherwise, jump ahead to “Interacting with the Node REPL”.

The first step is to download the source from Nodejs.org:

$ wget http://nodejs.org/dist/v0.12.15/node-v0.12.15.tar.gz

Next, you’ll need to extract the source in the downloaded file:

$ tar zxvf node-v0.12.15.tar.gz

This command unzips and extracts the Node source. For more information on the tar command options, execute man tar in your terminal.

Now that you have the source code on your computer, you need to run the configuration script in the source code directory. This script finds the required Node dependencies on your system and informs you if any are missing on your computer:

$ cd node-v0.12.15
$ ./configure

Once all dependencies have been found, the source code can then be compiled to a binary. This is done using the make command:

$ make

The last step is to run the make install command. This installs Node globally and requires sudo privileges:

$ sudo make install

If everything went smoothly, you should see output like the following when you check the Node.js version:

$ node -v
v0.12.15

Interacting with the Node REPL

Node is a runtime environment with a REPL (read–eval–print loop), which is a JavaScript shell that allows one to write JavaScript code and have it evaluated upon pressing Enter. It is like having the console from the Chrome developer tools in your terminal. You can try it out by entering a few basic commands:

$ node
> (new Date()).getTime();
1436887590047
>
(^C again to quit)
>
$

This is useful for testing out code snippets and debugging.

Managing Projects with npm

npm is the package manager for Node. It allows developers to easily reuse their code across projects and share their code with other developers. npm comes packaged with Node, so when you installed Node you also installed npm:

$ npm -v
2.7.0

There are numerous tutorials and extensive documentation on the Web for npm, which is beyond the scope of this book. In the examples in the book we will primarily be working with package.json files, which contain metadata for the project, and the init and install commands. We’ll use our application project as working example for learning how to leverage npm.

Initializing the Project

The npm CLI (command-line interface) is terminal program that allows you to quickly execute commands that help you manage your project/package. One of these commands is init.

init is an interactive command that will ask you a series of questions and create a package.json file for your project. This file contains the metadata for your project (package name, version, dependencies, etc.). This metadata is used to publish your package to the npm repository and to install your package from the repository. Let’s take a walk through the command:

$ npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sane defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.

The first prompt you’ll see is for the package name. This will default to the current directory name, which in our case is thaumoctopus-mimicus.

name: (thaumoctopus-mimicus)

Press enter to continue. The next prompt is for the version:

version: (0.0.0)

0.0.0 will do fine for now since we are just getting started and there will not be anything of significance to publish for some time. The next prompt is for a description of your project:

description:

Enter “Isomorphic JavaScript application example”. Next, you’ll be asked for for the entry point of your project:

entry point: (index.js)

The entry point is the file that is loaded when a user includes your package in his source code. index.js will suffice for now. The next prompt is the for the test command. Leave it blank (we will not be covering testing because it is outside the scope of this book):

test command:

Next, you’ll be prompted for the project’s GitHub repository. The default provided here is https://github.com/isomorphic-javascript-book/thaumoctopus-mimicus.git, which is this project’s repository. Yours will likely be blank.

git repository:
  (https://github.com/isomorphic-javascript-book/thaumoctopus-mimicus.git)

The next prompt is for keywords for the project:

keywords:

Enter “isomorphic javascript”. Then you’ll be asked for the author’s name:

author:

Enter your name here. The final prompt is for the license. The default value will be (ISC) MIT or (ISC), depending on the NPM version, which is what we want:

license: (ISC) MIT

If you navigate to the project directory you will now see a package.json file with the contents shown in Example 5-1.

{
  "name": "thaumoctopus-mimicus",
  "version": "0.0.0",
  "description": "Isomorphic JavaScript application example",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/isomorphic-javascript-book/thaumoctopus-mimicus.git"
  },
  "keywords": [
    "isomorphic",
    "javascript"
  ],
  "author": "Jason Strimpel",
  "license": "MIT",
  "bugs": {
    "url":
     "https://github.com/isomorphic-javascript-book/thaumoctopus-mimicus/issues"
  },
  "homepage": "https://github.com/isomorphic-javascript-book/thaumoctopus-mimicus"
}

Installing the Application Server

In the previous section, we initialized our project and created a package.json file that contains the metadata for our project. While this is a necessary process, it does not provide any functionality for our project, nor is it very exciting—so let’s get on with the show and have some fun!

All web applications, including isomorphic JavaScript applications, require an application server of sorts. Whether it is simply serving static files or assembling HTML document responses based on service requests and business logic, it is a necessary part and a good place to begin our coding journey together. For our application server we will be using hapi. Installing hapi is a very easy process:

$ npm install hapi --save

This command not only installs hapi, but also adds a dependency entry to the project’s package.json file. This is so that when someone (including you) installs your project, all the dependencies required to run the project are installed as well.

Now that we have hapi installed, we can write our first application server. The goal of this first example is to respond with “hello world”. In your index.js file, enter the code shown in Example 5-2.

var Hapi = require('hapi');

// Create a server with a host and port
var server = new Hapi.Server();
server.connection({
    host: 'localhost',
    port: 8000
});

// Add the route
server.route({
    method: 'GET',
    path:'/hello',
    handler: function (request, reply) {
       reply('hello world');
    }
});

// Start the server
server.start();

To start the application execute node . in your terminal, and open your browser to http://localhost:8000/hello. If you see “hello world”, congratulations! If not, review the previous steps and see if there is anything that you or I might have missed. If all else fails you can try copying this gist into your index.js file.

Writing Next-Generation JavaScript (ES6)

ECMAScript 6, or ES6, is the latest version of JavaScript, which adds quite a few new features to the language. The specification was approved and published on June 17, 2015. People have mixed opinions about some features, such as the introduction of classes, but overall ES6 has been well received and at the time of writing is being widely adopted by many companies.

The general consensus in the industry is to begin leveraging the new features afforded by ES6, which are not yet widely supported, now and to compile down to an ECMAScript version that is widely supported (i.e., ES5). Part of the compilation process is to provide polyfills for the ES6 features missing in the target version. Given this industry trend and readily available compilation support, we will be leveraging ES6 for the rest of the examples in this book. Let’s start with updating the code from the last example.

The first thing we want to change is how we are importing our dependency, hapi, in index.js. Replace the first line in the index.js file with this line:

import Hapi from 'hapi';

ES6 introduces the concept of a module system to JavaScript, which is a concept that has been missing since its inception. In the absence of a native module interface other patterns have emerged to fill the gap, such as AMD and CommonJS. The require syntax from the original index.js (Example 5-2) is the CommonJS format.

The next change we need to make is to our server variable declaration. Replace the second line in the file with:

const server = new Hapi.Server();

const is one of the new variable declarations available in ES6. When a variable is declared using const, the reference cannot be changed. For example, if you create an object using const and add properties to the object, that will not throw an error because the reference has not changed. However, if you attempted to point the variable to another object, that would result in an error because the reference would change. We use const because we don’t want to accidentally point our server variable to another reference.

Example 5-3 shows what the index.js file looks like with these changes in place.

import Hapi from 'hapi';

// Create a server with a host and port
const server = new Hapi.Server();
server.connection({
    host: 'localhost',
    port: 8000
});

// Add the route
server.route({
    method: 'GET',
    path:'/hello',
    handler: function (request, reply) {
       reply('hello world');
    }
});

// Start the server
server.start();

Now that we have updated index.js to use the latest and greatest ES6 syntax, let’s try running it. Depending on what version of Node you are running, your results may vary—that is, the browser might not render “hello world”. This is because ES6 may not be supported by the version of Node you are running. Fortunately, that is not a problem because there is a compiler that will take our ES6 code and compile it to code that runs in Node 4+.

Compiling from ES6 to ES5

One of the tools mentioned at the beginning of this chapter was Babel, a JavaScript compiler. We will be using Babel throughout the rest of the book to compile our JavaScript, but first we need to install Babel and the ES2015 transformations:

$ npm install --save-dev babel-cli babel-preset-es2015

Just like the hapi installation command, the previous command will add Babel as a dependency to your package.json file. The only difference is that we passed --save-dev instead of --save, so the dependency will be listed under devDependencies in the package.json file as opposed to the dependencies property. The reason for this is because Babel is not required to run your application, but it is a development requirement. This distinction makes it clear to consumers what dependencies are needed for production vs. development. When your project is installed using the --production flag, the Babel CLI will not be installed.

Now that we have successfully installed Babel we can compile index.js, but before we do that we should restructure our project a bit.

If we were to leave our project structure as is and compile index.js, then we would overwrite our source code—and losing your source code without a backup is not a great experience. The fix for this is to specify an output file for Babel. A common location for a project’s distributable is dist, and the common directory for source code is src. I’m not one for inventing new standards, so let’s just stick with those:

$ mkdir dist
$ mkdir src
$ mv index.js src/index.js

Now that we have a project structure that works well for compiling our source, let’s make a change to our package.json. The first change is pointing the main property to our new distributable by changing the "main": "index.js," line to "main": "./dist/index.js",. This informs Node of the new entry point for our application, so that when we execute node . it loads the correct script. We are now ready for our first compilation! Enter the following at the command line:

$ babel src/index.js --out-file dist/index.js

The previous command takes our source, src/index.js, compiles it, and creates our distributable, dist/index.js. If everything went well then we should be able to start up our server again using node ..

Setting Up a Development Workflow

We now have the ability to compile at will and restart the server via the command line, which is a great accomplishment, but stopping development each time to execute those two commands at the terminal will get old very quickly. Luckily, we are not the first people to have the need to automate repetitive tasks and optimize our workflow, so there are a few different automation choices at our disposal. Naturally we will want to pick the latest and greatest choice, so that our code will remain relevant for the next six months. The most recent addition to the JavaScript build world is Gulp, a streaming build system in which you create tasks and load plugins from the extensive community-driven ecosystem. These tasks can then be chained together to create your build process. Sounds great, right? Well, let’s get started. First we need to install Gulp:

$ npm install gulp --save-dev

The next thing we need to do is to create a gulpfile.js filr at the root of our project and define a default task, as shown in Example 5-4.

var gulp = require('gulp');

gulp.task('default', function () {
  console.log('default task success!');
});

Now that we have Gulp installed and a default task defined, let’s run it:

$ gulp
[20:00:11] Using gulpfile ./gulpfile.js
[20:00:11] Starting 'default'...
default task success!
[20:00:11] Finished 'default' after 157 μs

Success! We have Gulp running. Now let’s create a task of substance, like compiling our source. This will require the gulp-babel plugin, which we can install as follows:

$ npm install gulp-babel --save-dev

In our gulpfile.js we now need to modify our default task to handle the compilation. Replace the contents of the file you created earlier with the code shown in Example 5-5.

var gulp = require('gulp');
var babel = require('gulp-babel');

gulp.task('compile', function () {
  return gulp.src('src/**/*.js')
    .pipe(babel({
      presets: ['es2015']
    }))
    .pipe(gulp.dest('dist'));
});

gulp.task('default', ['compile']);

Now let’s run Gulp again:

$ gulp
[23:55:13] Using gulpfile ./gulpfile.js
[23:55:13] Starting 'compile'...
[23:55:13] Finished 'compile' after 251 ms
[23:55:13] Starting 'default'...
[23:55:13] Finished 'default' after 17 μs
$

This is great, but we are no better off than we were before. The only thing we have really done is to reduce the amount of code we have to type at the terminal. In order for the inclusion of Gulp to really add value we need to automate the compilation and server restarting on a source file save.

gulp.task('watch', function () {
  gulp.watch('src/**/*.js', ['compile']);
});

gulp.task('default', ['watch', 'compile']);

$ gulp
[00:04:35] Using gulpfile ./gulpfile.js
[00:04:35] Starting 'watch'...
[00:04:35] Finished 'watch' after 12 ms
[00:04:35] Starting 'compile'...
[00:04:35] Finished 'compile' after 114 ms
[00:04:35] Starting 'default'...
[00:04:35] Finished 'default' after 16 μs
[00:04:39] Starting 'compile'...
[00:04:39] Finished 'compile' after 75 ms

$ npm install gulp-nodemon --save-dev

$ npm install run-sequence --save-dev

var nodemon = require('gulp-nodemon');
var sequence = require('run-sequence');

gulp.task('start', function () {
  nodemon({
    watch: 'dist',
    script: 'dist/index.js',
    ext: 'js',
    env: { 'NODE_ENV': 'development' }
  });
});

gulp.task('default', function (callback) {
  sequence(['compile', 'watch'], 'start', callback);
});

$ gulp
[16:51:43] Using gulpfile ./gulpfile.js
[16:51:43] Starting 'default'...
[16:51:43] Starting 'compile'...
[16:51:43] Starting 'watch'...
[16:51:43] Finished 'watch' after 5.04 ms
[16:51:44] Finished 'compile' after 57 ms
[16:51:44] Starting 'start'...
[16:51:44] Finished 'start' after 849 μs
[16:51:44] Finished 'default' after 59 ms
[16:51:44] [nodemon] v1.4.0
[16:51:44] [nodemon] to restart at any time, enter `rs`
[16:51:44] [nodemon] watching: ./dist/**/*
[16:51:44] [nodemon] starting `node dist/index.js`
[16:51:47] Starting 'compile'...
[16:51:47] Finished 'compile' after 19 ms
[16:51:48] [nodemon] restarting due to changes...
[16:51:48] [nodemon] starting `node dist/index.js`

var gulp = require('gulp');
var babel = require('gulp-babel');
var nodemon = require('gulp-nodemon');
var sequence = require('run-sequence');

gulp.task('compile', function () {
  return gulp.src('src/**/*.js')
    .pipe(babel({
      presets: ['es2015']
    }))
    .pipe(gulp.dest('dist'));
});

gulp.task('watch', function () {
  gulp.watch('src/**/*.js', ['compile']);
});

gulp.task('start', function () {
  nodemon({
    watch: 'dist',
    script: 'dist/index.js',
    ext: 'js',
    env: { 'NODE_ENV': 'development' }
  });
});

gulp.task('default', function (callback) {
  sequence(['compile', 'watch'], 'start', callback);
});

Creating the Application Class

The first step to providing structure when responding to user requests is to create an application class that can be reused across your applications. The purpose of this class is to reduce boilerplate and provide an interface that will eventually be used on both the client and the server.

In the case of defining user routes we need an interface that will allow our application’s ./src/index.js file to do something like Example 7-1.

import Hapi from 'hapi';
import nunjucks from 'nunjucks';
import Application from './lib';

// configure nunjucks to read from the dist directory
nunjucks.configure('./dist');

// create a server with a host and port
const server = new Hapi.Server();
server.connection({
  host: 'localhost',
  port: 8000
});

function getName(request) {
  // function body omitted for brevity
}

const application = new Application({
  // responds to http://localhost:8000/
  '/': function (request, reply) {
    // read template and compile using context object
    nunjucks.render('index.html', getName(request), function (err, html) {
      // reply with HTML response
      reply(html);
    });
  }
}, {
  server: server
});

application.start();

If your first reaction to Example 7-1 was “I don’t see the benefit,” don’t worry; that is the correct reaction! We’d be wrong to do nothing more than implement an application class to support this code, because this would only encapsulate the implementation details without providing any benefits. In our case we are providing a foundation that we will progressively build upon, and the benefits will reveal themselves over the course of Part II. Now that we have cleared that up, let’s get to the implementation. We define our Application class in ./src/lib/index.js, as shown in Example 7-2.

export default class Application {

  constructor(routes, options) {
    this.server = options.server;
    this.registerRoutes(routes);
  }

  registerRoutes(routes) {
    for (let path in routes) {
      this.addRoute(path, routes[path]);
    }
  }

  addRoute(path, handler) {
    this.server.route({
      path: path,
      method: 'GET',
      handler: handler
    });
  }

  start() {
    this.server.start();
  }

}

We now have a basic application façade that we will eventually amend with a client implementation. This is a great start, but as noted earlier we haven’t added any real benefit to our application other than preparing it for transport to the client later. In order to add some value at this stage we need to reduce some of the boilerplate code associated with route definitions and add some more structure to how we are responding to user requests.

Creating a Controller

We can further improve the structure and reduce boilerplate by creating a common way to respond to URLs. In order to do that we need to create an interface that application developers can code against. As with the application structure we set up in Example 7-2, there will be little if any benefit at this point, within the context of current example, but we will build on this foundation.

In Struts, Ruby on Rails, ASP.Net, etc., controllers have action methods that are called by the framework. The controllers and actions are mapped to paths in a route table. These action methods contain the business logic for processing incoming requests and responding accordingly. In our case we want to respond with a user interface, which will be a payload of HTML. Knowing that, let’s begin by defining a basic interface, as shown in Example 7-3 (./src/lib/controller.js).

export default class Controller {

  constructor(context) {
    this.context = context;
  }

  index(application, request, reply, callback) {
    callback(null);
  }

  toString(callback) {
    callback(null, 'success');
  }

}

The constructor method creates an instance of the Controller class. The argument context contains metadata related to the route, such as path and query parameters. This data will be useful on the client when a controller instance persists after the action has replied to the request.

The index method is the default action for a controller instance, which accepts four arguments:

1. application is a reference to the application that defined the route. This will be useful in the future for accessing application-level methods and properties.

2. request is the hapi request object. This can be used for request-level actions such as reading header or cookie values. In the future this object will be normalized, so that it functions the same across the client and the server.

3. reply is the hapi reply object. This can be used to redirect a request, as in reply.redirect(some/url). In the future this object will be normalized, so that it functions the same across the client and the server.

4. callback is a Node-style callback for asynchronous control flow. If the first parameter is null, the handler that called the action method will proceed forward in the request/reply lifecycle. If it is an Error, the application responds with an error (we will cover error responses in more detail later).

toString is the method that will be called by the application framework after the action method callback has been executed without erring. The second parameter of a successful callback should be the string to be rendered.

Constructing a Controller Instance

Now that we have defined a contract for responding to resource requests, we can move more of the logic associated with defining routes to our application framework. If you remember, our ./src/index.js still contains route definitions with inline functions (see Example 7-4).

const application = new Application({
  // responds to http://localhost:8000/
  '/': function (request, reply) {
    // read template and compile using context object
    nunjucks.render('index.html', getName(request), function (err, html) {
      // reply with HTML response
      reply(html);
    });
  }
}, {
  server: server
});

Now that we have a base controller this can be transformed to the version in Example 7-5.

import Hapi from 'hapi';
import Application from './lib';
import Controller from './lib/controller'

const server = new Hapi.Server();
server.connection({
  host: 'localhost',
  port: 8000
});

const application = new Application({
  '/': Controller
}, {
  server: server
});

application.start();

That looks a lot better. We successfully removed the rendering and response implementation details, making our application much easier to read. At a glance we can now quickly discern that Controller will be responding to http://localhost:8000/. This is a true work of art. The downside is that it will not work! We need to implement code in src/lib/index.js that will create an instance that responds via a route handler. The change we need to make is to update our Application class’s addRoute method, as shown in Example 7-6, to create a handler that creates a controller instance and follows the lifecycle contract of the controller.

addRoute(path, Controller) {
  this.server.route({
    path: path,
    method: 'GET',
    handler: (request, reply) => {
      const controller = new Controller({
        query: request.query,
        params: request.params
      });

      controller.index(this, request, reply, (err) => {
        if (err) {
          return reply(err);
        }

        controller.toString((err, html) => {
          if (err) {
            return reply(err);
          }

          reply(html);
        });
      });
    }
  });
}

If you open up http://localhost:8000/ in your browser you should see “success,” which is the expected result, but not the desired result.

Extending the Controller

In our previous route handler we passed the file contexts of ./src/index.html to Nunjucks, compiled it, provided a context object, and finally replied with string that was the result of the template function. Let’s take a look at what this would look like in our new world. Example 7-7 shows the extended Controller class (./src/HelloController.js).

import Controller from './lib/controller';
import nunjucks from 'nunjucks';

// configure nunjucks to read from the dist directory
nunjucks.configure('./dist');

function getName(context) {
  // function body omitted for brevity
}

export default class HelloController extends Controller {

  toString(callback) {
    // read template and compile using context object
    nunjucks.render('index.html', getName(this.context), (err, html) => {
      if (err) {
        return callback(err, null);
      }
      callback(null, html);
    });
  }

}

This functions essentially the same as Example 7-4, but we have encapsulated the logic responsible for replying to http://localhost:8000/ in our controller. If we wanted, we could make this the base controller for the application and create some conventions for resolving to a template file based on the route. For instance, we could make the request.uri part of the context object and use request.uri.path to locate the template in a corresponding directory in ./dist. We are not going to implement this convention-based approach, but the point is that you can put common application-specific code in a base controller to promote reuse.

Next we need to update ./src/index.js to use our new controller and update the route path to accept optional path parameters, as seen in Example 7-8.

import Hapi from 'hapi';
import Application from './lib';
import HelloController from './hello-controller';

const server = new Hapi.Server();
server.connection({
  host: 'localhost',
  port: 8000
});

const application = new Application({
  '/hello/{name*}': HelloController
}, {
  server: server
});

application.start();

If you open up http://localhost:8000/ in your browser you should now see the expected hello message.

Improving the Response Flow

In preparation for porting the code to the client, there is one last implementation that we are going to change. Instead of the controller reading and creating the HTML response, we are going to create an API for returning a page template in which we can inject the results from the controller’s toString callback. The new version of ./src/HelloController.js can be seen in Example 7-9.

import Controller from './lib/controller';
import nunjucks from 'nunjucks';

function getName(context) {
  // function body omitted for brevity
}

export default class HelloController extends Controller {

  toString(callback) {
    nunjucks.renderString('<p>hello  </p>', getName(this.context), (err, html) => {
      if (err) {
        return callback(err, null);
      }
      callback(null, html);
    });
  }

}

The reason we are doing this is so that when our application transitions to an SPA on the client our routes will only return the HTML for a route as opposed to an entire document. This also has certain performance advantages. For example, on the server we could potentially limit the amount of file system I/O. On the client we could create a layout that has a header and footer that don’t rerender when navigating or that doesn’t require us to reparse <script> tags. From the application’s perspective, these are the changes that we will make to ./src/index.js (Example 7-10).

import Hapi from 'hapi';
import Application from './lib';
import HelloController from './hello-controller';
import nunjucks from 'nunjucks';

// configure nunjucks to read from the dist directory
nunjucks.configure('./dist');

const server = new Hapi.Server();
server.connection({
  host: 'localhost',
  port: 8000
});

const application = new Application({
  '/hello/{name*}': HelloController
}, {
  server: server,
  document: function (application, controller, request, reply, body, callback) {
    nunjucks.render('./index.html', { body: body }, (err, html) => {
      if (err) {
        return callback(err, null);
      }
      callback(null, html);
    });
  }
});

application.start();

These changes will allow us to inject a controller’s toString callback value, the body argument, into a page template without imposing a technology choice on the framework. Let’s implement the application framework changes now. The final version of the addRoute method is shown in Example 7-11.

addRoute(path, Controller) {
  this.server.route({
    path: path,
    method: 'GET',
    handler: (request, reply) => {
      const controller = new Controller({
        query: request.query,
        params: request.params
      });

      controller.index(this, request, reply, (err) => {
        if (err) {
          return reply(err);
        }

        controller.toString((err, html) => {
          if (err) {
            return reply(err);
          }

          this.document(this, controller, request, reply, html,
           function (err, html) {
            if (err) {
              return reply(err);
            }

            reply(html);
          });
        });
      });
    }
  });
}

Now the application framework is responsible for composing the HTML document response, but the implementation details of the HTML string construction are left up to the application developer. The final change we need to make is to our template, as seen in Example 7-12 (./src/index.html).

<head>
  <meta charset="utf-8">
  <title>
    And the man in the suit has just bought a new car
    From the profit he's made on your dreams
  </title>
</head>
<body>
  {{body}}
</body>
</html>

If we open the browser to http://localhost:8000/ we should see the expected “hello world” message.

Figure 7-1 illustrates the completed request/reply lifecycle.

Selecting a Bundling Library

There are two primary bundling libraries currently being leveraged by the community to create client application bundles: Browserify and Webpack.

Browserify was created to allow you to develop your client applications as if you were writing a Node application by using the Node require syntax to include dependencies. It also has client versions of some core Node libraries, so that you can include them and make use of their APIs as you would on the server.

Webpack was created to bundle all resource types—CSS, AMD, SASS, images, CoffeeScript, etc.—for the client. It has some built-in plugins and supports the concept of code splitting, which allows you to easily split your application into multiple files so that you do not have to load the entire application at once.

Both libraries are excellent choices, and you can accomplish the same results with either. Their approaches are just a bit different. We’ll be using Browserify because it will not require complex configuration for our use case, which makes it slightly easier to get started.

Creating Our Bundle Task

In this section we will create our first application bundle for the client. The bundle task itself is extremely easy to execute, but it requires some initial setup. The first step in the process is to install some new build tools, starting with the browserify module:

$ npm install browserify --save-dev

Later in the process we will use browserify to create a task in gulpfile.js that builds our application bundle. We also need to install the babelify module:

$ npm install babelify --save-dev

Babelify is a Browserify transform that transforms our source from ES6 to ES5, just like our compile task. This seems a bit redundant, but if we ever need to add other transforms in the future—e.g., brfs—then it will be necessary to bundle from source and use a transformer as opposed to bundling from the already compiled distribution. We will be piping a conventional text stream from Browserify to Gulp, so we need to install vinyl-source-stream as well:

$ npm install vinyl-source-stream --save-dev

Next we need to provide some instructions to Browserify, so that it will bundle up client-specific implementations when necessary. Adding the browser property to the package.json file, as shown here:

{
  "browser": {
    "./src/index.js": "./src/index.client.js"
  }
}

lets Browserify know that when it encounters a specific file, ./src/index.js, it should package a different file, .src/index.client.js, which contains an implementation for the client. This might seem a bit counterintuitive since we are writing code that is supposed to run on the client and the server, but there are times when we don’t really have an option (e.g., we can’t run a hapi server on the client). The key is to limit and isolate these patches of code to pieces that change infrequently, so that our daily development isn’t greatly impacted by context switching between environments.

The final step is to update our gulpfile.js file. First we need to include our newly installed modules:

var browserify = require('browserify');
var source = require('vinyl-source-stream');

Next we need to create our new bundle task:

gulp.task('bundle', function () {
  var b = browserify({
    entries: 'src/index.js',
    debug: true
  })
  .transform('babelify', { presets: ['es2015'] });

  return b.bundle()
    .pipe(source('build/application.js'))
    .pipe(gulp.dest('dist'));
});

This task will run ./src/index.client.js through browserify tracing any dependencies found. It creates a single file, which gets written to ./dist/build/application.js. Next, we will add the bundle task to our default task:

gulp.task('default', function (callback) {
  sequence(['compile', 'watch', 'copy', 'bundle'], 'start', callback);
});

Finally, we need to update our watch task so that the bundle is written when we make a source code change:

gulp.task('watch', function () {
  gulp.watch('src/**/*.js', ['compile', 'bundle'])
  gulp.watch('src/**/*.html', ['copy']);
});

That’s it! We are now ready to create our bundle—but first we need to add the client implementation that we specified in our package.json.

Adding Our Client Implementation

In ./src/index.js, the entry point for our application, we instantiate a hapi server. This is just the kind of environment-specific code that we need to ensure doesn’t make it to the client. We already took a look at how to specify different implementations for the client and the server in the previous section by leveraging the browser property in the package.json file, where we defined a file, ./src/index.client.js, to substitute for ./src/index.js. Our first pass on this will simply be to print “hello browser” to the console:

console.log('hello browser');

Now we need to include a link to the file in our application template ./src/index.html, as shown in Example 8-1.

<html>
  <head>
    <meta charset="utf-8">
    <title>
      And the man in the suit has just bought a new car
      From the profit he's made on your dreams
    </title>
  </head>
  <body>
    {{body}}
  </body>
  <script type="text/javascript" src={{application}}></script>
</html>

We will pass the path to the application bundle file as a property of the rendering context in ./src/index.js, as illustrated in Example 8-2.

const APP_FILE_PATH = '/application.js';
const application = new Application({
  '/hello/{name*}': HelloController
}, {
  server: server,
  document: function (application, controller, request, reply, body, callback) {
    nunjucks.render('./index.html', {
      body: body,
      application: APP_FILE_PATH
    }, (err, html) => {
      if (err) {
        return callback(err, null);
      }
      callback(null, html);
    });
  }
});

Finally, we need to add a route to our server in ./src/index.js that serves our bundle:

server.route({
  method: 'GET',
  path: APP_FILE_PATH,
  handler: (request, reply) => {
    reply.file('dist/build/application.js');
  }
});

Now when we execute our default Gulp task at the terminal and open http://localhost:8000/ in a browser we should see the same result, as before, but if we open the console in the browser we should see “hello browser”. If you see this message, then congratulations—you just served your first application bundle! While this example is trivial, the steps and understanding required to set it up will benefit us as we proceed with making our application isomorphic.

Leveraging the History API

Before the History API existed, SPAs used hash fragments as a workaround for routing to “pages” within an application on the client. Hash fragment changes create new entries in the browser history without reloading the page, but SEO is not supported because hash fragments are not sent to the server as part of an HTTP request. The reason they are not sent is because they were designed to link to a position in a document. The History API was created to ensure that URLs still serve their intended purpose—identifying unique resources—within SPAs and that their contents are properly indexed by search engines.

The History API is very simple. There is a stack onto which you can push a state object, title, and URL. For our purposes, mapping URLs to routes in a routing table, we are only concerned with two methods and one event:

History.replaceState

This method updates the most recent entry on the history stack. This is useful for adding a state object to a server-rendered page.

History.pushState

This method pushes a state object, optional title, and optional URL onto the stack. This is helpful for storing URL state that can be used to improve the responsiveness of client-side navigations. For example, all the data required to render a page could be stored in the state object, which could be used to short-circuit network requests for data when navigating to previously rendered pages.

PopStateEvent

This event is fired when the active history entry changes, such as when the user clicks the browser’s back button. Listening for this event can be used to trigger client-side navigations to a route.

These methods and this event will be used to trigger route requests for unique resources via URLs on the client, just as an HTTP GET request is used on the server.

Responding to and Calling the History API

In this section we will update our application core to work with the History API to facilitate client-side routing. Before we implement this, though, a word of caution. In this section we will be creating our first real abstraction. I typically avoid abstractions like the plague because they hide details, which obfuscates meaning, making code more difficult to follow and brittle—as James Coplien says, “Abstraction is evil.” However, sometimes abstractions are necessary, which is true in this case because we cannot run a server on the client.

In “Adding Our Client Implementation” we created a client bundle that logged “hello browser”. The entry point for this bundle was ./src/index.js, which we configured in our package.json to point to the client implementation, ./src/index.client.js, of ./src/index.js, which is the entry point for the server. This server entry imports the application core, ./src/lib/index.js, and starts the application. We need to follow the same form for the client implementation, as shown in Example 8-3.

import Application from './lib';
import HelloController from './HelloController';

const application = new Application({
  '/hello/{name*}': HelloController
}, {
  // query selector for the element in which
  // the controller response should be injected
  target: 'body'
});

application.start();

Next we need implement the client Application class that will encapsulate the History API code—but first we need to add a new property to our package.json browser field:

{
  "browser": {
    "./src/index.js": "./src/index.client.js",
    "./src/lib/index.js": "./src/lib/index.client.js"
  }
}

This will instruct Browserify to use ./src/lib/index.client.js when bundling. Now we can start to fill in our Application class in ./src/lib/index.client.js, as seen in Example 8-4.

export default class Application {

  navigate(url, push=true) {

  }

  start() {

  }

}

This is the form against which we will be coding in this section. We will begin by implementing the start method. The first thing we need to do is add an event listener for the PopStateEvent (Example 8-5).

navigate(url, push=true) {
 console.log(url);
}

start() {
  // create event listener popstate
  this.popStateListener = window.addEventListener('popstate', (e) => {
    let { pathname, search} = window.location;
    let url = `${pathname}${search}`;
    this.navigate(url, false);
  });
}

For the time being this event handler simply logs the current URL so that we can confirm that it is working as expected. In “Routing on the Client” we will hook in our client-side routing, which will execute a route handler that matches the URL.

Next we need to implement an opt-in click event handler that will be used to execute a route handler when a user clicks on an href or another element that opts-in and provides the required data. The opt in should be declarative and unobtrusive, so that the application framework can easily listen for clicks without impacting the rest of the application. A good mechanism for achieving this goal is using data-* attributes. We can use this interface to define our own data-* attribute and use it to detect click events that should be handled by the application framework (Example 8-6).

  start() {
    // create event listener popstate
    this.popStateListener = window.addEventListener('popstate', (e) => {
      // body omitted for brevity
    });

    // create click listener that delegates to navigate method
    // if it meets the criteria for executing
    this.clickListener = document.addEventListener('click', (e) => {
      let { target } = e;
      let identifier = target.dataset.navigate;
      let href = target.getAttribute('href');

      if (identifier !== undefined) {
        // if user clicked on an href then prevent
        // the default browser action (loading a new HTML doc)
        if (href) {
          e.preventDefault();
        }

        // navigate using the identifier if one was defined.
        // or the href
        this.navigate(identifier || href);
      }
    });
  }

This implementation places a single event listener on the document, filters by the data attribute data-navigate, and calls a new (yet to be implemented) method called navigate if it meets the identifying criteria. Next, we need to implement the navigate method referenced in the click event handler (Example 8-7).

navigate(url, push=true) {
  // if browser does not support the History API
  // then set location and return
  if (!history.pushState) {
    window.location = url;
    return;
  }

 console.log(url);

  // only push history stack if push
  // argument is true
  if (push) {
    history.pushState({}, null, url);
  }
}

The navigate method is another placeholder executing a route handler that matches a URL against a path in a routing table. For now we are just pushing an empty state object and a URL onto the history stack to confirm that it works.

Now that we have our stub implementations, we need to update our template for the /{name*} route with some links to test our stubs. Currently the template is a hardcoded string in the HelloController class (defined in ./src/hello-controller.js), because it was simple and did not warrant the overhead of a filesystem read. However, since we are expanding the template, now seems like a good time to move it to a separate file, ./src/hello.html (Example 8-8).

<p>hello {{fname}} {{lname}}</p>
<ul>
  <li><a href="/mortimer/smith" data-navigate>Mortimer Smith</a></li>
  <li><a href="/bird/person" data-navigate>Bird Person</a></li>
  <li><a href="/revolio/clockberg" data-navigate>Revolio Clockberg</a></li>
</ul>

Lastly, we need to update the HelloController class (Example 7-7) to read the template from the filesystem, as shown in Example 8-9.

toString(callback) {

  nunjucks.render('hello.html', getName(this.context), (err, html) => {
    if (err) {
      return callback(err, null);
    }

    callback(null, html);
  });
}

If you execute gulp in the terminal and open your browser to http://localhost:8000, you should see the new page with the links. You should be able to click through the links, see the address bar update in the browser, and see the log statements in the console. You should see the same behavior when using the browser’s forward and backward history controls. We now have our hooks into the browser history!

On the surface these stubs that make use of the History API appear trivial, but they will be the resource request interface to our application, just like the HTTP GET request is on the server. The common factor between the server and client implementations is the URL. It is like the signature of a function. This signature is then used to match a route in a routing table. On the server the routing table is part of hapi. On the client we cannot run hapi, but we should use the same router, so that routes are matched and applied using the same algorithm. In the next section we will explore how this can be accomplished.

Executing the Controller Response Flow

Now that we can match URLs to controllers, we can execute the same response flow as we did on the server:

1. Create a controller instance.

2. Execute a controller action.

3. Render a response.

navigate(url, push=true) {
  // preceding code omitted for brevity

  if (route && Controller) {
    const controller = new Controller({
      query: search,
      params: params
    });
  }

  // following code omitted for brevity
}

$ npm install query-string --save

navigate(url, push=true) {
  // preceding code omitted for brevity

  if (route && Controller) {
    const controller = new Controller({
      // parse search string into object
      query: query.parse(search),
      params: params
    });
  }
}

 navigate(url, push=true) {
   // preceding code omitted for brevity

   if (route && Controller) {
     const controller = new Controller({
       // parse search string into object
       query: query.parse(search),
       params: params
     });

     // request and reply stubs; facades will be
     // implemented in the next chapter
     const request = () => {};
     const reply = () => {};
     // execute controller action
     controller.index(this, request, reply, (err) => {
       if (err) {
         return reply(err);
       }
     });
   }
 }

Rendering a controller response

On the client we need to allow for an alternate rendering implementation for toString in ./src/lib/Controller.js:

render(target, callback) {
  this.toString(function (err, body) {
    if (err) {
      return callback(err, null);
    }

    document.querySelector(target).innerHTML = body;
    callback(null, body);
  });
}

This will allow us to take advantage of different rendering patterns optimized for the client, such as the React.js virtual DOM, as opposed to a template library that uses string concatenation.

If you run the default Gulp task in the terminal, open your browser to http://localhost:8000/, and navigate through the links you will now see the page change, but not in the manner anticipated. The hello message is always “hello hello.html Sanchez”. This is because we have not configured Nunjucks for the client or added a handler on the server to process template file requests, so each request returns ./src/index.html and the controller uses the path parameter “index.html” for fname. Let’s fix this. In .src/index.client.js (Example 8-13), we’ll configure Nunjucks to read from the absolute path of /templates on the browser.

Example 8-13. Configuring Nunjucks for the client

import Application from './lib';
import HelloController from './hello-controller';
import nunjucks from 'nunjucks';

// configure nunjucks to read from the dist directory
nunjucks.configure('/templates');

const application = new Application({
  '/hello/{name*}': HelloController
}, {
  // query selector for the element in which
  // the controller response should be injected
  target: 'body'
});

application.start();

Now Nunjucks will make Ajax requests for /templates/{template_file_name}. Next we need to add a handler to the server to reply with the appropriate template in ./src/index.js, as seen in Example 8-14.

Example 8-14. Defining a route handler for template files

import Hapi from 'hapi';
import Application from './lib';
import HelloController from './hello-controller';
import nunjucks from 'nunjucks';
import path from 'path';

// section omitted for brevity

server.route({
  method: 'GET',
  path: '/templates/{template*}',
  handler: {
    file: (request) => {
      return path.join('dist', request.params.template);
    }
  }
});

// following code omitted for brevity

Now if we go back to the browser and navigate through the links we should see the name changing accordingly as we render the controller response as described in Figure 8-1. Success! We now have the basis for our isomorphic JavaScript application! However, we left behind a bit of mess, so in the next section we will do some housekeeping.

Note

We are making a non-cached Ajax call for every template in this example. This isn’t very efficient, but it is simple, defers loading, and works well when developing. In some cases you will want to precompile your templates for the client, and sometimes the server as well.

Figure 8-1. Navigation in response to href click event

Defining the API

A cookie is comprised of key/value pairs separated by equals signs, with optional attributes that are delimited by semicolons:

HTTP/1.0 200 OK
Content-type: text/html
Set-Cookie: bnwq=You can't consume much if you sit still and read books;
Expires=Mon, 20 Apr 2015 16:20:00 GMT

The HTTP cookie in this example is sent as part of the request header to the server or received in the response header by the browser. This uniform exchange format allows the client and server to implement interfaces for getting and setting these values. Unfortunately, the interfaces are not consistent across environments. This is because on servers, unlike in browsers, there is not a standard interface. This is by design because server responsibilities are varied and they differ greatly from browsers, which are intended to be platforms for running (W3C) standards-based user interfaces. These differences are precisely why we are creating an abstraction. However, before we can create a common interface for getting and setting cookies across the client and the server we need to know the different environment interfaces—i.e., we need to gain the domain knowledge required to create a proper abstraction.

Story=With Folded Hands;Novel=The Humanoids

function getCookieByName(name) {
  let cookies = document.cookie.split(';')

  for (let i = 0; i < cookies.length; i++) {
    let [key, value] = cookies[i].split('=');
    if (key === name) {
      return value;
    }
  }
}

document.cookie="bnwq=A love of nature keeps no factories busy;path=/"

import http from 'http';

function getCookieByName(name, cookies) {
  for (let i = 0; i < cookies.length; i++) {
    let [key, value] = cookies[i].split('=');
    if (key === name) {
      return value;
    }
  }
}

http.createServer(function (request, response) {
  let someCookie = getCookieByName('some-cookie', request.headers.cookies);
  response.end('Hello World\n');
}).listen(8080);

import Hapi from 'hapi';

const server = new Hapi.Server({
  debug: {
    request: ['error']
  }

  server.route({
    method: 'GET',
    path: {anything*},
    handler: (request, reply) => {
      let someCookie = request.state['some-cookie'];
      reply('Hello World\n');
    }
  });
});

server.start();

import http from 'http';

http.createServer(function (request, response) {
   response.writeHead(200, {
     'Set-Cookie': 'some-cookie=some value',
     'Content-Type': 'text/plain'
   });
  response.end('Hello World\n');
}).listen(8080);

import Hapi from 'hapi';

const server = new Hapi.Server({
  debug: {
    request: ['error']
  }

  server.route({
    method: 'GET',
    path: {anything*},
    handler: (request, reply) => {
      reply('Hello World\n').state('some-cookie', 'some value');
    }
  });
});

server.start();

class Cookie {

  // name (String): cookie name
  // value (String): cookie value
  // options.secure (Boolean): https only
  // options.expires (Number): expiration time in milliseconds
  // options.path (String): restrict cookie to a specific path
  // options.domain (String): restrict cookie to a specific domain
  // Returns: Undefined
  set(name, value, options = {}) {

  }

  // name (String): cookie name
  // Returns: cookie value (String); default null
  get(name) {

  }

}

 constructor(context) {
   this.context = context;
 }

$ npm install cookies-js --save

import cookie from 'cookies-js';

export default {

  get(name) {
    return cookie.get(name) || undefined;
  },

  set(name, value, options = {}) {
    // convert milliseconds to seconds for cookies-js api
    if (options.expires) {
      options.expires / 1000;
    }
    cookie.set(name, value, options);
  }

}

export default function (request, reply) {

  // encoding functions http://www.rfc-editor.org/rfc/rfc6265.txt
  // follows same patterns as 'cookies-js' that is used on the client
  function cleanName(name) {
    name = name.replace(/[^#$&+\^`|]/g, encodeURIComponent);
    return name.replace(/\(/g, '%28').replace(/\)/g, '%29');
  }

  function cleanValue(value) {
    return (value + '').replace(/[^!#$&-+\--:<-\[\]-~]/g, encodeURIComponent);
  }

  return {

    get(name) {
      return request.state[name] && decodeURIComponent(request.state[name]) ||
        undefined;
    },

    set(name, value, options = {}) {
      reply.state(cleanName(name), cleanValue(value), {
        // use hapi defaults if values are falsy
        isSecure: options.secure || false,
        path: options.path || null,
        ttl: options.expires || null,
        domain: options.domain || null
      });
    }

  };

}

// code omitted for brevity
import cookie from './cookie.client';
// code omitted for brevity

export default class Application {
  // code omitted for brevity
  navigate(url, push=true) {
    // code omitted for brevity
    const controller = new Controller({
      // parse search string into object
      query: query.parse(search),
      params: params,
      cookie: cookie
    });
    // code omitted for brevity
  }
  // code omitted for brevity
}

import cookieFactory from './cookie';

export default class Application {
  // code omitted for brevity
  addRoute(path, Controller) {
    // code omitted for brevity
    const controller = new Controller({
      query: request.query,
      params: request.params,
      cookie: cookieFactory(request, reply)
    });
    // code omitted for brevity
  }
}

Cookie example

Now we should be able to set and get cookies on both the client and the server, as shown in Example 9-10.

Example 9-10. Isomorphic set cookie example in HelloController class (Example 7-7) index method, ./src/HelloController.js

index(application, request, reply, callback) {
  this.context.cookie.set('random', '_' + (Math.floor(Math.random() * 1000) + 1),
  { path: '/' });
  callback(null);
}

Figure 9-1 shows how our isomorphic cookie getter and setter works.

Figure 9-1. Isomorphic cookie getter and setter

Defining the API

In “Getting and Setting Cookies”, we learned that there is not a consistent way to set cookies on the server, but that there is a standard contract for sending the information over the Internet. The same is true of redirects on the server. The client does not have the concept of creating HTTP redirects, but it does have the ability to update the location (URL), which makes a new HTTP request. As with getting and setting cookies, the API is consistent across browsers. Again let’s follow best practices and better familiarize ourselves with the environments for which we will be creating an abstraction before we define an interface.

window.location = 'http://theoatmeal.com/';
// OR
window.location.assign('http://theoatmeal.com/');

import http from 'http';

http.createServer(function (request, response) {
   response.writeHead(302, {
     'Location': 'http://theoatmeal.com/',
     'Content-Type': 'text/plain'
   });
  response.end('Hello World\n');
}).listen(8080);

import Hapi from 'hapi';

const server = new Hapi.Server({
  debug: {
    request: ['error']
  }

  server.route({
    method: 'GET',
    path: {anything*},
    handler: (request, reply) => {
      reply.redirect('http://theoatmeal.com/');
    }
  });
});

server.start();

export default function (application) {

  const reply = function () {};

  reply.redirect = function (url) {
    application.navigate(url);
    return this;
  };

  reply.temporary = function () {
    return this;
  },

  reply.rewritable = function () {
    return this;
  },

  reply.permanent = function () {
    return this;
  }

  return reply;

}

// code omitted for brevity
import replyFactory from './reply.client';
// code omitted for brevity

export default class Application {
  // code omitted for brevity
  navigate(url, push=true) {
    // code omitted for brevity
    const request = () => {};
    const reply = replyFactory(this);
    // code omitted for brevity
  }
  // code omitted for brevity
}

Redirection example

In the examples thus far the entry point for the HelloController has been /hello/{name*}. This works great, but what if we want the users to see the greeting message when they access the application root, http://localhost:8000/? We could set up another route that points to this controller, but what if we only wanted to show this message the first time a user access the application? Our cookie and redirect APIs can handle this (see Example 9-16).

Example 9-16. HomeController class redirection example (./src/HomeController.js)

import Controller from './lib/Controller';

export default class HomeController extends Controller {

  index(application, request, reply, callback) {
    if (!this.context.cookie.get('greeting')) {
      this.context.cookie.set('greeting', '1', {
       expires: 1000 * 60 * 60 * 24 * 365 });
    }

    return reply.redirect('/hello');
  }

  toString(callback) {
    callback(null, 'I am the home page.');
  }

}

Next we need to add our new controller to a route:

const application = new Application({
  '/hello/{name*}': HelloController,
  '/': HomeController
}, options);

Finally, let’s add a new link to hello.html, so that we can navigate to/on the client:

<p>hello  </p>
<ul>
  <li><a href="/hello/mortimer/smith" data-navigate>Mortimer Smith</a></li>
  <li><a href="/hello/bird/person" data-navigate>Bird Person</a></li>
  <li><a href="/hello/revolio/clockberg" data-navigate>Revolio Clockberg</a></li>
  <li><a href="/" data-navigate>Home Redirect</a></li>
</ul>

Now when we access http://localhost:8000/ on the client or the server it will redirect us to http://localhost:8000/hello. This approach provides us with the flexibility to implement different conditional redirects and to set the HTTP codes accordingly.

Figure 9-2 illustrates our isomorphic redirect abstraction.

Figure 9-2. Isomorphic redirect