Webapp Builder can be used with zero configuration to manage your static assets, which means that any node.js application that serves static files can benefit from the automatic refresh feature of webapp. As an additional benefit, the default configuration for webapp will package CommonJS modules and compile CoffeeScript and LessCSS for you.

Let's start by using a simple Express application.

var express = require('express');
var app = express();
app.get('/hello', function(req, res){
  res.send('Hello World');
});
app.use(express.static(__dirname + '/public'));
app.listen(3000);
console.log("Listening at http://localhost:3000/");

When we run node app.js, files in the public directory will be served by the static server. The first advantage we can get from webapp is its server-side monitoring. To enable that, we just run the server program through webapp:

sudo npm install -g webapp-builder
webapp monitor app.js

Now webapp is monitoring all of the modules referenced by app.js, and whenever any one of them changes it will automatically kill and restart the server program. This means that as we begin to integrate webapp's static server, we no longer need to switch to the terminal, kill the process, and restart it ourselves.

With that out of the way, let's switch from express.static to webapp:

var express = require('express');
var webapp = require('webapp-builder');
var app = express();
var server = app.listen(3000);
app.get('/hello', function(req, res){
  res.send('Hello World');
});
app.use(webapp({
  sourcePath: __dirname + "/public",
  autoRefreshUsingServer: server,
  fallthrough: false
}));
console.log("Listening at http://localhost:3000/");

Save the file and, violĂ , the server has already restarted and is now serving static files with webapp. Open up http://localhost:3000/ you'll see that webapp is instructing you to create an index.html file to get started. Create a simple index.html file and save it.

<!DOCTYPE html>
<html>
  <head>
    <title>Auto refreshing</title>
  </head>
  <body>
    <p>Webapp will automatically refresh the browser when this file is modified!</p>
  </body>
</html>

Already, the browser has refreshed to show this HTML page. Webapp will continue to refresh the page as you develop. What's more, webapp tracks client-side dependencies as well, so if you reference a CSS file from the HTML and modify the stylesheet, the browser tabs showing that HTML page will be refreshed. Note that webapp is intelligent about rebuilding files and will only rebuild them if the file contents have changed. Internally, it hashes each source file and stores the hash, and will only trigger a rebuild (and refresh) if the hash changes.

For a demo of the packaging and compilation features supported by webapp, check out this video.

Options available to webapp

When we instantiated the webapp middleware, we provided some options. Let's look at what those did and what the other options available are:

  • sourcePath - this defines the directory that the original source files are kept.
  • autoRefreshUsingServer - by passing an http server here, webapp will create a socket.io server and enable automatic refreshes. This is accomplished by adding a snippet of JavaScript to files ending in .html.
  • fallthrough - by setting this to true, we instruct webapp that it should serve 404 errors when resources are not available. Errors served by webapp in this way are also automatically refreshing, meaning that the error will disappear once the file is created.

Other options are:

  • autoRefreshUsingSocketIO - if you are already using socket.io in your application, you can provide the socket.io object instead to have webapp share it. The messages are namedspaced under /webapp.
  • targetPath - this defines the directory that built output files are kept. Under the hood, webapp builds files and stores them in this directory, then uses express.static to serve them to provide client-side caching and partial download support.
  • verbose - this controls how much logging webapp should do. Defaults to 2; maximum logging level is 5.