Advanced

Launching

With Nodemon

Nodemon is a good tool to use during development. It will watch for file changes and restart the application as necessary. The --exec argument can be used to have nodemon launch the BlueOak server.

nodemon --exec blueoak-server

Programatically

Launch BlueOak server programmatically by using init.

var server = require('blueoak-server');

server.init(function(err) {
    if (err) {
        console.warn('Startup failed', err);
    } else {
        console.log('started');
    }
});

It's also possible to specify an alternate application directory using the appDir option in init.

server.init({
    appDir: process.cwd()
}, function(err) {
...
});

With npm start

If installing modules globally isn't desired, you can install BlueOak Server locally, npm install blueoak-server, and add a start script to the package.json for launching the server.

  "scripts": {
    "start": "blueoak-server",
    "test": "..."
  }

Running npm start will then launch the server.

Error Handling

Middleware

Express has a concept of error-handling middleware, which is a special form of middleware that uses 4-arguments instead of 3:

app.use(function(err, req, res, next) {
  ...
});

Built-in Error Handler

There's a built-in error handler, which upon getting an error will log the stack trace and respond with a 500.

Custom Error Handler

To create a custom error handler, first create a js file in the middleware directory that registers the error handler.

exports.init = function (app, logger) {
    app.use(function (err, req, res, next) {
        res.status(500);
    }
}

Express requires that error-handling middleware be registered last, after middleware and route handlers. In order to register the middleware last, there's a special middleware$ field in the config specifically for error handling middleware.

"express": {
    "middleware": ["csrf", "cors", "session", "body-parser"],
    "middleware$": ["my-error-handler"]
}

Crash Dumps

Crash dumps are a way of getting detailed logs from crashes without having to enable debug logs. The problem with keeping debug log levels enabled is that it can produce too much log output. Using the crash dump setting, you can get a limited amount of debug output only during a crash (uncaughtException).

To enable, add the crashDump block to your config.

"crashDump": {
  "enabled": true,
  "length": 1000,
  "type": "console"
}

When a crash occurs, the last few lines (configurable through length) of logs will be written to stdout, along with additional environment details.

---------- Crash Report Tue Jan 19 2016 11:17:15 GMT-0500 (EST) ----------
PID:          12948
Uptime:       8.126s
Heap used:    28274536
Heap total:   60038496
1453220228360 info: monitor - Monitoring is disabled.
1453220228374 info: auth - Starting auth services
1453220228381 info: express - App is listening on http://:::3000
1453220228382 info: blueoak-server.js - Server started