Express

High performance, high class web development for Node.js

• Home
• Guide
• Screencasts
• Applications

Express 1.x to 2.x Migration

HTTPS

Creating an HTTPS server is simply, simply pass the TLS options to express.createServer():

 var app = express.createServer({
     key: ...
   , cert: ...
 });

 app.listen(443);

req.header() Referrer

Previously if anyone was doing something similar to:

 req.headers.referrer || req.headers.referer
 req.header('Referrer') || req.header('Referer')

With the new special-case we may now simply use Referrer which will return either if defined:

 req.header('Referrer')

res.local(name, val)

Previously all local variables had to be passed to res.render(), or either app.helpers() or app.dynamicHelpers(), now we may do this at the request-level progressively. The res.local() method accepts a name and val, however the locals passed to res.render() will take precedence.

For example we may utilize this feature to create locals in middleware:

 function loadUser(req, res, next) {
   User.get(req.params.id, function(err, user){
     res.local('user', user);
     next();
   });
 }

 app.get('/user/:id', loadUser, function(req, res){
   res.render('user');
 });

req.param(name[, defaultValue])

Previously only name was accepted, so some of you may have been doing the following:

 var id = req.param('id') || req.user.id;

The new defaultValue argument can handle this nicely:

 var id = req.param('id', req.user.id);

app.helpers() / app.locals()

app.locals() is now an alias of app.helpers(), as helpers makes more sense for functions.

req.accepts(type)

req.accepts() now accepts extensions:

  // Accept: text/html
  req.accepts('html');
  req.accepts('.html');
  // => true

  // Accept: text/*; application/json
  req.accepts('html');
  req.accepts('text/*');
  req.accepts('text/plain');
  req.accepts('application/json');
  // => true

  req.accepts('image/png');
  req.accepts('png');
  // => false

res.cookie()

Previously only directly values could be passed, so for example:

res.cookie('rememberme', 'yes', { expires: new Date(Date.now() + 900000) });

However now we have the alternative maxAge property which may be used to set expires relative to Date.now() in milliseconds, so our example above can now become:

res.cookie('rememberme', 'yes', { maxAge: 900000 });

res.download() / res.sendfile()

Both of these methods now utilize Connect’s static file server behind the scenes (actually the previous Express code was ported to Connect 1.0). With this change comes a change to the callback as well. Previously the path and stream were passed, however now only an error is passed, when no error has occurred the callback will be invoked indicating that the file transfer is complete. The callback remains optional:

 res.download('/path/to/file');

 res.download('/path/to/file', function(err){
   if (err) {
     console.error(err);
   } else {
     console.log('transferred');
   }
 });

The stream threshold setting was removed.

res.render()

Previously locals were passed as a separate key:

 res.render('user', { layout: false, locals: { user: user }});

In Express 2.0 both the locals and the options are one in the same, meaning you cannot have a local variable named layout as it is reserved for express, however this cleans up the API:

 res.render('user', { layout: false, user: user });

res.partial()

Express 2.0 adds the res.partial() method, helpful for rendering partial fragments over WebSockets or Ajax requests etc. The API is identical to the partial() calls within views.

 // render a collection of comments
 res.partial('comment', [comment1, comment2]); 

 // render a single comment
 res.partial('comment', comment);

partial() locals

Both res.partial() and the partial() functions accept a single object consisting of both the options and the locals. Previously with Express 1.x you may pass user to a partial, along with date like so:

   partial('user', { object: user, locals: { date: new Date }})

or perhaps if you preferred not to use the inferred name user you may used a local for this as well:

   partial('user', { locals: { user: user, date: new Date }})

With recent changes to Express 2.x the object passed is now both, so the following is valid for the object option and locals:

   partial('user', { object: user, date: new Date })

Or the following which is equivalent, however the local var name is explicitly set to user instead of deduced from the filename.

   partial('user', { user: user, date: new Date })

When a “basic” object aka {} or new Object is passed, it is considered options, otherwise it is considered the object. The following are equivalent:

  partial('user', user); 
  partial('user', { object: user }); 

Template Engine Compliance

To comply with Express previously engines needed the following signature:

 engine.render(str, options, function(err){});

Now they must export a compile() function, returning a function which when called with local variables will render the template. This allows Express to cache the compiled function in memory during production.

 var fn = engine.compile(str, options);
 fn(locals);

View Partial Lookup

Previously partials were loaded relative to the now removed view partials directory setting, or by default views/partials, now they are relative to the view calling them, read more on view lookup.

Mime Types

Express and Connect now utilize the mime module in npm, so to add more use:

 require('mime').define({ 'foo/bar': ['foo', 'bar'] });

static() middleware

Previously named staticProvider(), the now static() middleware takes a single directory path, followed by options.

 app.use(express.static(__dirname + '/public', { maxAge: oneYear }));

Previously when using options the root option would be used for this:

 app.use(express.staticProvider({ root: __dirname + '/public', maxAge: oneYear }));