Migrating from 2.x to 3.x

Removed

• res.render() "status" option (use res.statusCode=)
• res.render() "charset" option (use res.charset=)
• app.dynamicHelpers() (use app.locals.use(callback))
• app.helpers() (use app.locals)
• the concept of a "layout" (template engine specific now)
• partial() (template engine specific)
• res.partial()
• "view options" setting, use app.locals
• "hints" setting
• req.isXMLHttpRequest (use req.xhr)
• app.error() (use middleware with (err, req, res, next))

Changed

• res.send(body[, code]) is now res.send([code,] body)
• res.redirect(url[, code]) is now res.redirect([code,] url)
• res.json(obj[, code]) is now res.json([code,] obj)
• renamed app.register() to app.engine()
• template engine compliance from engine.compile(str, options) => Function to engine.__express(filename, options, callback)

Template engine integration

Express 2x template engine compatibility required the following module export:

exports.compile = function(templateString, options) {
  return a Function;
};

Express 3x template engines should export the following:

exports.__express = function(filename, options, callback) {
  callback(err, string);
};

If a template engine does not expose this method, you're not out of luck, the app.engine() method allows you to map any function to an extension. Suppose you had a markdown library and wanted to render .md files, but this library did not support Express, your app.engine() call may look something like this:

var markdown = require('some-markdown-library');

app.engine('md', function(path, options, fn){
  fs.readFile(path, 'utf8', function(err, str){
    if (err) return fn(err);
    str = markdown.parse(str).toString();
    fn(null, str);
  });
});

View system changes

By removing the concept of a "layout" & partials in Express 3.x template engines will have greater control over file I/O. This means integration with template engines much easier, and greatly simplify the view system's internals.

This also enables template engines to supply their own means of inheritance, for example later releases of Jade provide Django-inspired template inheritance, where the view being rendering specifies the layout it wants to extend.

Error handling middleware

.. todo

App- & Request-level local variables

.. todo