Skip to content

Migrating from 3.x to 4.x

Jump to bottom
Douglas Christopher Wilson edited this page Jun 12, 2014 · 36 revisions

Express 3.x to 4.0 migration guide. You may also be interested in New features in 4.x.

See Express 4.x docs for more examples and complete API documentation.

Overview

Express 4 no longer has Connect as a dependency. This means that ALL bundled middleware (except static) is no longer available on the express module. Each middleware is available as a module. (More on this below.)

This change allows middleware to receive fixes, updates, and releases, without impacting Express release cycles (and vice-versa).

These are not direct replacements. Please read their documentation before blindly using them with old arguments.

Others documented here: https://github.com/senchalabs/connect#middleware

Removals

app.configure()

This method is no longer available.

If you wish to configure different routes based on environment, use an if statement, or another module.

app.configure('development', function() {
   // configure stuff here
});
// becomes
var env = process.env.NODE_ENV || 'development';
if ('development' == env) {
   // configure stuff here
}

app.router

The middleware stack has been overhauled! This reduces confusion with .use vs .get (or other HTTP verbs).

As a result, the need to manually do app.use(app.router) has been removed. See the Routers section (below) on the new middleware and routing API.

If you had code that looked like this:

app.use(cookieParser());
app.use(bodyParser());
/// .. other middleware .. doesn't matter what
app.use(app.router); // **this line will be removed**

// more middleware (executes after routes)
app.use(function(req, res, next);
// error handling middleware
app.use(function(err, req, res, next) {});

app.get('/' ...);
app.post(...);

app.router has been removed. Middleware and routes are now executed in the order they're added.

Your code should move any calls to app.use that came after app.use(app.router) after any routes (HTTP verbs).

app.use(cookieParser());
app.use(bodyParser());
/// .. other middleware .. doesn't matter what

app.get('/' ...);
app.post(...);

// more middleware (executes after routes)
app.use(function(req, res, next);
// error handling middleware
app.use(function(err, req, res, next) {});

express.createServer()

Long deprecated. Just create new apps with express().

Connect middleware

All Connect middleware lives in separate modules (with the exception of express.static which is provided for convenience). Everything else benefits from being a separate module, with its own versioning.

connect patches

Connect patched Node's prototypes globally. This is considered bad behaviour, and was removed in Connect 3.

Some of these patches are:

  • res.on('header')
  • res.charset
  • res.headerSent Uses Node's res.headersSent instead

You should no longer use these in any Connect or Express libraries.

res.charset

If you want Express to set a default charset (and you should!), use res.set('content-type') or res.type() to set the header.

A default charset will NOT be added when using res.setHeader().

Changed

app.use

app.use now accepts :params.

app.use('/users/:user_id', function(req, res, next) {
  // req.params.user_id exists here
});

req.accepted()

Use req.accepts() instead.

  • req.accepts()
  • req.acceptsEncodings()
  • req.acceptsCharsets()
  • req.acceptsLanguages()

All use accepts internally. Please refer to accepts for any issues or documentation requests.

Note that these properties may have changed from arrays to functions. To continue using them as "arrays", call them without arguments. For example, req.acceptsLanguages() // => ['en', 'es', 'fr'].

res.location()

No longer does relative URL resolution. Browsers will handle relative URLs themselves.

app.route -> app.mountpath

When mounting an Express app in another Express app.

Configuration Changes

  • json spaces In development, this is no longer enabled by default.

req.params

Is now an object instead of an array. This won't break your app if you used the req.params[##] style for regexp routes where parameter names are unknown.

res.locals

It is no longer a function, but a plain object. Treat it as such.

res.headerSent

Changed to headersSent to match the Node.js ServerResponse object.

You probably never used this, so it probably won't be an issue.

req.is

Uses type-is internally now. Please refer to type-is for any issues or documentation requests.

Added

app.route(path)

Returns a new Route instance. A Route is invoked when a request matching the route path is received. Routes can have their own middleware stacks. They also have methods for the HTTP VERBS to process requests.

See the Routes and Routing docs for more details on creating routes in Express.

Router and Route middleware

The Router has been overhauled to be a full-fledged middleware router.

The Router is a good way to separate your routes into files/modules—without sacrificing features like parameter matching and middleware.

See the Routes and Routing docs.

Clone this wiki locally