Migrating from 2.x to 3.x

Removed

• res.render() "status" option (use node's res.statusCode= or res.status(code).render(...))
• res.render() "charset" option (use res.charset=)
• app.dynamicHelpers() (use app.locals.use(callback)) see example below.
• 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))
• req.flash() (just use sessions: req.session.messages = ['foo'] etc)
  • connect-flash can be used as middleware to provide req.flash()

Dynamic Helpers Example

Express 2x

app.dynamicHelpers({
  session: function(req, res){
    return req.session;
  }
});

Express 3x

app.locals.use(function(req, res, done) {
  res.locals.session = req.session;
  done();
});

Or since we don't need async in this case:

app.locals.use(function(req, res) {
  res.locals.session = req.session;
});

This is more powerful, not only because we now have async support, you can define several locals using the same resource. The following contrived example would expose name and email to views.

app.locals.use(function(req, res, done){
  User.get(id, function(err, user){
    if (err) return done(err);
    res.locals.name = user.name;
    res.locals.email = user.email;
    done();
  });
});

Changed

• req.header(field[, defaultValue]) replaced by req.get(field) (remains for backwards compatibility)
• res.header(field[, value]) replaced by res.set(field, value) / res.get(field) (remains for backwards compatibility)
• 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)
• express.createServer() is now simply express() (but remains for BC)
• Use express.cookieParser('secret') instead of passing the secret to the express.session() middleware. The 'secret' option in the express.session() middleware has been removed.

Application function

The return value of express() is a JavaScript Function, encapsulating everything that makes an Express app tick. This means you can easily setup HTTP and HTTPS versions of your application by passing it to node's http.createServer() and https.createServer():

...
var app = express();
http.createServer(app).listen(80);
https.createServer(options, app).listen(443);

For convenience, and smaller applications the app.listen() method takes the same arguments, wrapping in an HTTP server. The following are equivalent:

var app = express();
app.listen(3000);

and

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

http.createServer(app).listen(3000);

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 rendered specifies the layout it wants to extend. For an example of this using the Jade engine visit http://www.devthought.com/code/use-jade-blocks-not-layouts/

Post-release we may end up building an Express extension to support the old partial() concept.

Error handling middleware

.. todo

App- & Request-level local variables

.. todo