Skip to content

Migrating from 2.x to 3.x

Coreh edited this page Jul 30, 2012 · 48 revisions

Removed

  • res.render() "status" option (use node's res.statusCode= or res.status(code).render(...))
  • res.render() "charset" option (use res.charset=)
  • res.local(name, value) (use res.locals.name = value or res.locals({ name: value }) instead)
  • app.dynamicHelpers() (use middleware + res.locals)
  • 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'] or similar)
  • connect-flash can be used as middleware to provide req.flash()

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).
    • Keep in mind that the return value of express() is no longer an http.Server instance. (See the Application function section below for more details)
  • 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.

View options

The "view options" setting is no longer necessary, app.locals are the local variables merged with res.render()'s, so app.locals.pretty = true is the same as passing res.render(view, { pretty: true }).

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);

This however means that methods that are on node's http.Server.prototype are no longer present on app, for example app.address() must now be called on the server returned by app.listen() or the one you have wrapped with http.createServer(app).

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

The app.error(callback) method in 2.x was effectively the same as the following:

app.error = function(fn){
  this.use(function(err, req, res, next){
    fn.apply(this, arguments);
  });
};

The reason for this is that Connect differentiates between "regular" middleware, and "error-handling" middleware via the fn.length. A regular middleware has a fn.length of <= 3, aka (req, res, next), whereas error-handling middleware must have exactly 4 (err, req, res, next). So the reason 2.x wrapped this functionality was to simply provide a bit of sugar on-top of this API making the parameters optional.

In short all you need to do to "catch" these errors that are passed along is to define another middleware, but with 4 arguments. Note that this middleware should be defined below all the others, so that they may invoke next(err) in order to pass an error to it like so:

app.use(express.bodyParser())
app.use(express.cookieParser())
app.use(express.session())
app.use(app.router) // the router itself (app.get(), app.put() etc)
app.use(function(err, req, res, next){
  // if an error occurs Connect will pass it down
  // through these "error-handling" middleware
  // allowing you to respond however you like
  res.send(500, { error: 'Sorry something bad happened!' });
})

App- & Request-level local variables

.. todo

Clone this wiki locally