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