MEAN web development #4: All aboard the Node.js Express!

Hi everyone. After my little excursion to Polymer we’re back at MEAN web development! In my previous MEAN post about Node.js I asked you what you wanted to read next, Express or MongoDB. I got a request for Express, so that’s what this post will be about. Don’t worry, we’ll get to MongoDB later. If you’re not up and running yet you can check out my previous posts.

  1. MEAN web development #1: MEAN, the what and why
  2. MEAN web development #2: Node.js in the back
  3. MEAN web development #3: More Node.js
  4. MEAN web development #4: All aboard the Node.js Express!
  5. MEAN web development #5: Jade and Express
  6. MEAN web development #6: AngularJS in the front
  7. MEAN web development #7: MongoDB and Mongoose
  8. MEAN web development #8: Sockets will rock your socks!
  9. MEAN web development #9: Some last remarks

The code examples for this post are, as usual, on my GitHub account in the mean4-blog repository.

Also be sure to follow me on Twitter @sanderrossel for industry updates and more blogs on MEAN, Node.js, Express, MongoDB, AngularJS and related technologies.

Express

Express is a pretty generic framework for Node.js, or a minimal and flexible Node.js web application framework as they put it.
Node.js is pretty bare bones and has only the most basic server functionality. That’s a good thing because that means other people, like the Express team, can do things their way. And so Express just handles a lot of the low level work for you. Parsing paths and queries, check; routing, check; templating, check. So it’s no wonder that Express is a pretty popular Node.js framework! There are some alternatives for Express, like Koa and Hapi, but I won’t discuss those here.

I have already explained how to install Node.js and add Express to your project in MEAN web development #1: MEAN, the what and why and we’ve used some Express in MEAN web development #2: Node.js in the back. So if you haven’t read those articles yet I suggest you read them now. Don’t forget about nodemon either, a very nice tool for testing Node.js applications!

Starting from this post I’m also just going to host our sites on port 80 (instead of 1337). This has the advantage that we can just visit localhost instead of localhost:portNumber because 80 is the default HTTP port. That said, other applications might use port 80 (like SQL Server Management Studio Reporting Services). If port 80 isn’t working for you simply use another port (or make port 80 available by closing the application that’s using it).

Routing

In MEAN web development #2: Node.js in the back we’ve already seen some routing examples. Let’s go over that again real quick and see some other really nice routing features of Express.js!

So let’s say you have a very simple website with a homepage and an about page. Your Node.js Express server JavaScript file may look a bit like this.

var express = require('express');
var app = express();

app.get(['/', '/index'], function(req, res) {
    res.send('This is the homepage!');
});

app.get('/about', function(req, res) {
    res.send('This is the about page!');
});

var server = app.listen(80, '127.0.0.1');

That’s cool, but what if you wanted to log every request you got? Sure, you could create a function and call it in both handlers, but if you get a lot of handlers that will become a little tiresome. Especially when you’re going to move your routing to external files. And after you’ve added the logging you want to implement some login handler and some blacklist checker and… Well you get the point.
What I haven’t told you yet is that you can chain request handlers so you can reuse them. Let’s check that out. For your homepage it may look like this.

var express = require('express');
var app = express();

app.get(['/', '/index'], function(req, res, next) {
        console.log(req.originalUrl + ' requested @ ' + new Date().toISOString());
        next();
    }, function(req, res) {
        res.send('This is the homepage.');
});

var server = app.listen(80, '127.0.0.1');

By specifying the next parameter in the first callback function and executing it the next handler will be called. Failing to either call next() or res.send() will make your website very unresponsive (it just freezes, so don’t forget). So here we get a logging of each request to our homepage.

And now we can easily refactor that and implement it for the about page too.

var express = require('express');
var app = express();

var logger = function(req, res, next) {
    console.log(req.originalUrl + ' requested @ ' + new Date().toISOString());
    next();
};

app.get(['/', '/index'], logger, function(req, res) {
    res.send('This is the homepage.');
});

app.get('/about', logger, function(req, res) {
    res.send('This is the about page.');
});

var server = app.listen(80, '127.0.0.1');

Now let’s add a blacklisted handler to our site. Usually you would have some list of blacklisted IP addresses and reject them access, but since we’re testing from localhost I’m just going to check for a blacklisted query parameter. Notice that the blacklisted function either calls res.send() or next(). We can pass in an array of handlers to app.get(), so that makes our lives a little easier.

var express = require('express');
var app = express();

var logger = function(req, res, next) {
    console.log(req.originalUrl + ' requested @ ' + new Date().toISOString());
    next();
};

var blacklisted = function(req, res, next) {
    if (req.query.blacklisted == 'true') {
        res.send('You are blacklisted on this site!');
    } else {
        next();
    };
};

var globalReqHandlers = [logger, blacklisted];

app.get(['/', '/index'], globalReqHandlers, function(req, res) {
    res.send('This is the homepage.');
});

app.get('/about', globalReqHandlers, function(req, res) {
    res.send('This is the about page.');
});

var server = app.listen(80, '127.0.0.1');

You can get ‘blacklisted’ by adding “?blacklisted=true” to the end of your URL, for example “localhost/about?blacklisted=true”. So that’s pretty cool! But it gets better. We can use app.use(). This will append some request handlers (also called middleware) to the routings. Be sure you add your handlers in the correct order as they’re executed in the same order you added them. So this would look as follows.

var globalReqHandlers = [logger, blacklisted];

app.use('/', globalReqHandlers);

app.get(['/', '/index'], function(req, res) {
    res.send('This is the homepage.');
});

app.get('/about', function(req, res) {
    res.send('This is the about page.');
});

Notice that the listener for the homepage and the about page no longer have the globalReqHandlers specified, but the requests will still be logged.

So let’s add a little admin panel. Whenever someone accesses the admin panel we want to make sure this user is an admin. How would this go?

app.use('/', globalReqHandlers);
app.use('/admin', function(req, res, next) {
    if (req.query.admin == 'true') {
        next();
    } else {
        res.send('You are not an admin on this site!');
    };
});

/* Homepage and about... */

app.get('/admin', function(req, res) {
    res.send('This is the admin panel.');
});

app.get('/admin/users', function(req, res) {
    res.send('This is the admin users page.');
});

Whenever you now try to access an admin page you need to be an admin (by adding “?admin=true” at the end of your URL). Notice that a request for an admin page still gets logged and checked for the blacklist. The homepage and about page, however, don’t check if the user is an admin.

So you can imagine this stuff clutters up your server file pretty quickly. Let’s move these routing handlers to separate files. If you’re unfamiliar with modules in Node.js I suggest you read my previous MEAN article, MEAN web development #3: More Node.js.

So create two files in node_modules, called routing.js and routingAdmin.js.

Here is the code for routing.js.

var express = require('express');
var router = express.Router();

var logger = function(req, res, next) {
    console.log(req.originalUrl + ' requested @ ' + new Date().toISOString());
    next();
};

var blacklisted = function(req, res, next) {
    if (req.query.blacklisted == 'true') {
        res.send('You are blacklisted on this site!');
    } else {
        next();
    };
};

var globalReqHandlers = [logger, blacklisted];

router.use('/', globalReqHandlers);

router.get(['/', '/index'], function(req, res) {
    res.send('This is the homepage.');
});

router.get('/about', function(req, res) {
    res.send('This is the about page.');
});

module.exports = router;

And here’s the code for adminRouting.js.

var express = require('express');
var router = express.Router();

router.use('/', function(req, res, next) {
    if (req.query.admin == 'true') {
        next();
    } else {
        res.send('You are not an admin on this site!');
    };
});

router.get('/', function(req, res) {
    res.send('This is the admin panel.');
});

router.get('/users', function(req, res) {
    res.send('This is the admin users page.');
});

module.exports = router;

So we’re using the Express.Router object and do much the same to it as we did with app earlier. Do notice that I’m just mapping to ‘/’ and ‘/users’ in the adminRouter though. In our server file we can now use these modules as follows.

var express = require('express');
var routing = require('routing');
var adminRouting = require('adminRouting');
var app = express();

app.use('/', routing);
app.use('/admin', adminRouting);

var server = app.listen(80, '127.0.0.1');

So as you can see I can now use and reuse the routing! And it is here that I map the admin routings to /admin. So how cool is that? I thought so too!

There’s one last thing I’d like to show you. I won’t implement it, but I thought you’d like to know it’s there since it’s pretty cool! You can use app.route() to chain HTTP methods to a request. So far we’ve only seen GET (app.get()), but app has a method for each HTTP method (app.post(), app.put(), app.delete()…).

app.route('/admin/users')
    .get(function(req, res, next) {
        // Handle GET here...
    })
    .post(function(req, res, next) {
        // Handle POST here...
    }) // etc.
);

404

So now that we have all of our routing in place we can define a handler for the well known 404! So if all else fails, and a request couldn’t be handled, we return this. Luckily that’s really very easy.

app.use('*', function(req, res) {
    res.status(404).send("Well, looks like we've got a four-o-four, boys! (That mean the page was not found)");
});

We simply hook up another middleware! The ‘*’ is a wildcard character and means it responds to anything we throw at it. For this reason it’s very important to put the 404 handler after all your other handlers! Remember that your handlers are executed in the order you add them to your app, so if this one is added before anything else this will handle the request and anything after this will be ignored. Notice I’m setting the status to 404, which is the HTTP status code for “Not Found” and let’s the browser know the page couldn’t be found. You can set any status using Response.status(), but usually you won’t have to. Other status codes include 200, OK (the default); 202, Accepted; 400, Bad Request; 403, Forbidden and 500, Bad Request (and there’s lots more).

I’d like to focus on the wildcard for a bit. There are a few patterns you can match, including any Regular Expression.
* means just any character(s). So ‘/sander‘ would match ‘sanderrossel’, but also ‘sanderexpress’ or just ‘sander’. ‘/sanderss*’ would match ‘sanderrossel’ and ‘sanderexpress’, but not ‘sandernodejs’.
A character may appear more than once. You can use a plus symbol, for example ‘/go+gle’ (coun’t the amount of zeroes and navigate to that page in the search results?). Of course it matches ‘gogle’, ‘google’, ‘gooogle’ and so on.
You can also mix in optional characters using the questionmark. For example ‘/express?’ would match ‘express’ and ‘expres’.
You can group characters using parenthesis. ‘/express(js)?’ matches ‘express’ and ‘expressjs’, but not ‘expressj’.
Why would you use this? You can now write a single handler for ‘page’, ‘page.htm’, ‘page.html’, etc. That’s pretty neat!

You can play around with it by adding the following middleware to your server (before the 404) and browsing to localhost/yourpatternhere (or ‘yourcoolpattttern’, ‘yourpatternhere’ or ‘yourawesomepattttternhere’, but not ‘yourpatter’ or ‘yourpaternhere’).

app.get('/your*patt+ern(here)?', function(req, res) {
    res.send('Matched the pattern!');
});

Error handling

So what happens when something goes wrong? Perhaps your connection to the database failed when looking up that blacklist. Luckily adding some error handling isn’t difficult. Just add another middleware! The error handler needs to have four parameters passed to it, whether you use them or not. That way Express knows it’s an error handler.

app.use('/', function(err, req, res, next) {
    console.error(err.stack);
    res.status(500).send('Oops, looks like you broke something!');
});

You need to add that even after your 404, after all 404-ing may cause an error! So now we only need to have an error to test this. You can add the following code (before the 404!) and browse to localhost/error.

app.get('/error', function(req, res) {
    // something is undefined.
    var error = 1 / something;
    res.send('Code will never come here.');
});

Of course you can add specific error handlers for specific pages. Simply change the path of your handler. For example, the following code will only handle any errors on admin pages.

app.use('/admin', function(err, req, res, next) {
    console.error(err.stack);
    res.status(500).send("Oops, looks like you broke something! That's not very admin-ish of you!");
});

Do notice I’m setting the status to 500. You can use the error object for information about the error.

And of course you can chain error handlers. Keep in mind that only the first handler needs the err parameter!

var logger = function(err, req, res, next) {
    console.error(err.stack);
    next();
};

var dbLogger = function(req, res, next) {
    console.log('Error logged to DB.');
    next();
};

var serveErrPage = function(req, res, next) {
    res.status(500).send('Oops, looks like you broke something!');
};

app.use('/', logger, dbLogger, serveErrPage);

And what happens if even your error handling fails? Guess you better set up a safety net.

app.use('/', logger, dbLogger, serveErrPage);
app.use('/', function(err, req, res, next) {
    // Everything failed...
    res.status(500).send('Even the error handling is bugged...');
});

And we can generate an optional error by, you guessed it, passing it in as a query parameter. Let’s handle it in the logger function.

var logger = function(err, req, res, next) {
    if (req.query.err == 'true') {
        var error = 1 / somethingElse;
    };
    console.error(err.stack);
    next();
};

So localhost/error for the regular error handling. localhost/error?err=true to generate an error in the error handling.

Of course you could’ve put the error handlers in the routing file too! I won’t do that, but just know that it’s an option.

One last thing. The app.get(), app.use() etc. all have a path parameter, it’s the ‘/’, ‘/admin’ parameter. It’s optional. I’ve specified it every time for clarity, but you may omit it and it will default to ‘/’.
So app.use(‘/’, handler) is the same thing as app.use(handler).

In this post we’ve taken a good deep look at the routing functionality of Express. As you can see it’s all pretty easy. There’s more you can do with Express, especially when you install some third-party middleware, like cookie-parser, cookie-session, express-session or compression.
There’s an important feature of Express that we haven’t seen yet, which is templating. You can use template engines, like Jade or Mustache, with Node.js and Express. We’ll use Express and Jade in a later post!

And, as usual, I’m going to recommend some books. First there’s the Succinctly ebooks by Syncfusion that I keep recommending because they’re great and they’re free. If you feel you’re still not up to speed, or looking to get up to speed, with Node.js and Express take a look at JavaScript Succinctly, Node.js Succinctly and HTTP Succinctly.
I can also recommend the books by Manning Publications. They have some good stuff on Node.js and Express!

Stay tuned!

Leave a Reply