مطالعهٔ Express Docs

مسیریابی، میان‌افزار

باز کردن مرجع کامل دانلود آرشیو مستندات ناشر

گزیده‌ای از مستندات Express Docs · نسخهٔ 14b435df23ad · طبق مجوز مستندات مخزن رسمی

مسیریابی

_Routing_ refers to how an application's endpoints (URIs) respond to client requests. For an introduction to routing, see Basic routing.

You define routing using methods of the Express app object that correspond to HTTP methods; for example, app.get() to handle GET requests and app.post to handle POST requests. For a full list, see app.METHOD. You can also use app.all() to handle all HTTP methods and app.use() to specify middleware as the callback function (See Using middleware for details).

These routing methods specify a callback function (sometimes called a "handler function") that Express automatically runs when the application receives a request matching the specified route (endpoint) and HTTP method. In other words, the application "listens" for requests that match the specified route(s) and method(s), and when it detects a match, it calls the specified callback function.

In fact, the routing methods can have more than one callback function as arguments. With multiple callback functions, it is important to provide next as an argument to the callback function and then call next() within the body of the function to hand off control to the next callback.

The following code is an example of a very basic route.

cjs title="index.cjs"
const express = require('express');
const app = express();

// respond with "hello world" when a GET request is made to the homepage
app.get('/', (req, res) => {
  res.send('hello world');
});
mjs title="index.mjs"

const app = express();

// respond with "hello world" when a GET request is made to the homepage
app.get('/', (req, res) => {
  res.send('hello world');
});
ts title="index.ts"

const app: Express = express();

// respond with "hello world" when a GET request is made to the homepage
app.get('/', (req: Request, res: Response) => {
  res.send('hello world');
});

Route methods

A route method is derived from one of the HTTP methods, and is attached to an instance of the express class.

The following code is an example of routes that are defined for the GET and the POST methods to the root of the app.

js
// GET method route
app.get('/', (req, res) => {
  res.send('GET request to the homepage');
});

// POST method route
app.post('/', (req, res) => {
  res.send('POST request to the homepage');
});
ts

// GET method route
app.get('/', (req: Request, res: Response) => {
  res.send('GET request to the homepage');
});

// POST method route
app.post('/', (req: Request, res: Response) => {
  res.send('POST request to the homepage');
});

Express supports methods that correspond to all HTTP request methods: get, post, and so on. For a full list, see app.METHOD.

There is a special routing method, app.all(), used to load middleware functions at a path for _all_ HTTP request methods. For example, the following handler is executed for requests to the route "/secret" whether using GET, QUERY, POST, PUT, DELETE, or any other HTTP request method supported in the http module.

js
app.all('/secret', (req, res, next) => {
  console.log('Accessing the secret section ...');
  next(); // pass control to the next handler
});
ts

app.all('/secret', (req: Request, res: Response, next: NextFunction) => {
  console.log('Accessing the secret section ...');
  next(); // pass control to the next handler
});

Route paths

Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings or regular expressions. They can also capture values from the URL, as described in Route parameters below.

<Alert type="info">

Express uses path-to-regexp v8 for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. Express Playground Router is a handy tool for testing basic Express routes, although it does not support pattern matching.

</Alert>

String paths

String paths match requests exactly. The dot (.) and hyphen (-) are interpreted literally.

<Alert type="warning">Query strings are not part of the route path.</Alert>

js
app.get('/', (req, res) => {
  res.send('root');
});

app.get('/about', (req, res) => {
  res.send('about');
});

app.get('/random.text', (req, res) => {
  res.send('random.text');
});
ts

app.get('/', (req: Request, res: Response) => {
  res.send('root');
});

app.get('/about', (req: Request, res: Response) => {
  res.send('about');
});

app.get('/random.text', (req: Request, res: Response) => {
  res.send('random.text');
});

<Alert type="alert">

The characters ?, +, *, [], (), and ! are reserved and cannot be used as literal characters in route paths, and braces are reserved for optional segments. Use \ to escape them if needed.

</Alert>

Regular expressions

You can also use regular expressions as route paths. This is useful when you need more complex matching logic.

js
// Matches any path containing "a"
app.get(/a/, (req, res) => {
  res.send('/a/');
});

// Matches paths ending with "fly" (butterfly, dragonfly, etc.)
app.get(/.*fly$/, (req, res) => {
  res.send('/.*fly$/');
});
ts

// Matches any path containing "a"
app.get(/a/, (req: Request, res: Response) => {
  res.send('/a/');
});

// Matches paths ending with "fly" (butterfly, dragonfly, etc.)
app.get(/.*fly$/, (req: Request, res: Response) => {
  res.send('/.*fly$/');
});

Route parameters

Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the req.params object, with the name of the route parameter specified in the path as their respective keys. They come in three forms: named parameters (:name), wildcards (*name), and optional segments, which wrap either of them in braces.

Named parameters

Named parameters capture a single path segment at their position in the URL, or part of one when combined with literal characters, as shown further below.

text
Route path: /users/:userId/books/:bookId
Request URL: http://localhost:3000/users/34/books/8989
req.params: { "userId": "34", "bookId": "8989" }

To define routes with route parameters, simply specify the route parameters in the path of the route as shown below.

js
app.get('/users/:userId/books/:bookId', (req, res) => {
  res.send(req.params);
});

In TypeScript, @types/express infers the parameters from the route path, so in the handler above req.params.userId and req.params.bookId are already typed as string with no extra annotation. Reading a name that is not in the route (such as req.params.other) is a type error. You only need to annotate the parameters when the handler is defined separately from the route, because the type checker can no longer see the path. In that case, pass them as the first type argument of Request:

ts

const sendParams = (req: Request<{ userId: string; bookId: string }>, res: Response) => {
  res.send(req.params);
};

app.get('/users/:userId/books/:bookId', sendParams);

<Alert type="alert">

The name of route parameters must be a valid JavaScript identifier. Other names can be used by quoting them, for example :"user-name".

</Alert>

Since the hyphen (-) and the dot (.) are interpreted literally, they can be used along with route parameters for useful purposes.

text
Route path: /flights/:from-:to
Request URL: http://localhost:3000/flights/LAX-SFO
req.params: { "from": "LAX", "to": "SFO" }
text
Route path: /plantae/:genus.:species
Request URL: http://localhost:3000/plantae/Prunus.persica
req.params: { "genus": "Prunus", "species": "persica" }

<Alert type="alert">

Regexp characters are not supported inside string paths, so a parameter cannot be restricted with a suffix such as :userId(\d+). Use an array of paths or a full regular expression instead. See the path route matching syntax for more information.

</Alert>

Wildcards

Wildcards match any path after a prefix. Like other route parameters they must have a name, but they are captured as an array of path segments instead of a string.

js
app.get('/files/*filepath', (req, res) => {
  // GET /files/images/logo.png
  console.dir(req.params.filepath);
  // => [ 'images', 'logo.png' ]
  res.send(`File: ${req.params.filepath.join('/')}`);
});
ts

app.get('/files/*filepath', (req: Request<{ filepath: string[] }>, res: Response) => {
  // GET /files/images/logo.png
  console.dir(req.params.filepath);
  // => [ 'images', 'logo.png' ]
  res.send(`File: ${req.params.filepath.join('/')}`);
});

To also match the root path, wrap the wildcard in braces:

js
// Matches / , /foo , /foo/bar , etc.
app.get('/{*splat}', (req, res) => {
  // GET / => req.params = {}, splat is omitted
  // GET /foo/bar => req.params.splat = [ 'foo', 'bar' ]
  res.send('ok');
});
ts

// Matches / , /foo , /foo/bar , etc.
app.get('/{*splat}', (req: Request, res: Response) => {
  // GET / => req.params = {}, splat is omitted
  // GET /foo/bar => req.params.splat = [ 'foo', 'bar' ]
  res.send('ok');
});

Optional segments

Use braces to define optional segments in a route path. When the segment is not present, the parameter is omitted from req.params.

js
app.get('/:file{.:ext}', (req, res) => {
  // GET /image.png => req.params = { file: 'image', ext: 'png' }
  // GET /image => req.params = { file: 'image' }
  res.send('ok');
});
ts

app.get('/:file{.:ext}', (req: Request, res: Response) => {
  // GET /image.png => req.params = { file: 'image', ext: 'png' }
  // GET /image => req.params = { file: 'image' }
  res.send('ok');
});

The braces can also wrap a whole parameter to make it optional. Note that everything inside the braces is optional, so the position of the slash matters:

js
app.get('/user/{:id}', (req, res) => {
  // GET /user/42 => req.params = { id: '42' }
  // GET /user/ => req.params = {}
  // GET /user => 404, only the parameter is optional
  res.send('ok');
});

app.get('/order{/:id}', (req, res) => {
  // GET /order/42 => req.params = { id: '42' }
  // GET /order => req.params = {}, the whole segment is optional
  res.send('ok');
});
ts

app.get('/user/{:id}', (req: Request, res: Response) => {
  // GET /user/42 => req.params = { id: '42' }
  // GET /user/ => req.params = {}
  // GET /user => 404, only the parameter is optional
  res.send('ok');
});

app.get('/order{/:id}', (req: Request, res: Response) => {
  // GET /order/42 => req.params = { id: '42' }
  // GET /order => req.params = {}, the whole segment is optional
  res.send('ok');
});

Do not confuse the position of the slash in the route path with the [strict routing setting](/api/application/#application-settings), which is about the request URL: it controls whether a URL ending in a slash that the route path does not require still matches. For example, a request for /order/ matches the /order{/:id} route by default, but returns a 404 error when strict routing is enabled; the trailing slash of /user/ is unaffected because the /user/{:id} route requires it. All the requests commented in the examples above behave the same regardless of that setting.

Route handlers

You can provide multiple callback functions that behave like middleware to handle a request. The only exception is that these callbacks might invoke next('route') to bypass the remaining route callbacks. You can use this mechanism to impose pre-conditions on a route, then pass control to subsequent routes if there's no reason to proceed with the current route.

js
app.get('/user/:id', (req, res, next) => {
  if (req.params.id === '0') {
    return next('route');
  }
  res.send(`User ${req.params.id}`);
});

app.get('/user/:id', (req, res) => {
  res.send('Special handler for user ID 0');
});
ts

app.get('/user/:id', (req: Request, res: Response, next: NextFunction) => {
  if (req.params.id === '0') {
    return next('route');
  }
  res.send(`User ${req.params.id}`);
});

app.get('/user/:id', (req: Request, res: Response) => {
  res.send('Special handler for user ID 0');
});

In this example:

  • GET /user/5 → handled by first route → sends "User 5"
  • GET /user/0 → first route calls next('route'), skipping to the next matching /user/:id route

Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples.

A single callback function can handle a route. For example:

js
app.get('/example/a', (req, res) => {
  res.send('Hello from A!');
});
ts

app.get('/example/a', (req: Request, res: Response) => {
  res.send('Hello from A!');
});

More than one callback function can handle a route (make sure you specify the next object). For example:

js
app.get(
  '/example/b',
  (req, res, next) => {
    console.log('the response will be sent by the next function ...');
    next();
  },
  (req, res) => {
    res.send('Hello from B!');
  }
);
ts

app.get(
  '/example/b',
  (req: Request, res: Response, next: NextFunction) => {
    console.log('the response will be sent by the next function ...');
    next();
  },
  (req: Request, res: Response) => {
    res.send('Hello from B!');
  }
);

An array of callback functions can handle a route. For example:

js
const cb0 = function (req, res, next) {
  console.log('CB0');
  next();
};

const cb1 = function (req, res, next) {
  console.log('CB1');
  next();
};

const cb2 = function (req, res) {
  res.send('Hello from C!');
};

app.get('/example/c', [cb0, cb1, cb2]);
ts

const cb0 = function (req: Request, res: Response, next: NextFunction) {
  console.log('CB0');
  next();
};

const cb1 = function (req: Request, res: Response, next: NextFunction) {
  console.log('CB1');
  next();
};

const cb2 = function (req: Request, res: Response) {
  res.send('Hello from C!');
};

app.get('/example/c', [cb0, cb1, cb2]);

A combination of independent functions and arrays of functions can handle a route. For example:

js
const cb0 = function (req, res, next) {
  console.log('CB0');
  next();
};

const cb1 = function (req, res, next) {
  console.log('CB1');
  next();
};

app.get(
  '/example/d',
  [cb0, cb1],
  (req, res, next) => {
    console.log('the response will be sent by the next function ...');
    next();
  },
  (req, res) => {
    res.send('Hello from D!');
  }
);
ts

const cb0 = function (req: Request, res: Response, next: NextFunction) {
  console.log('CB0');
  next();
};

const cb1 = function (req: Request, res: Response, next: NextFunction) {
  console.log('CB1');
  next();
};

app.get(
  '/example/d',
  [cb0, cb1],
  (req: Request, res: Response, next: NextFunction) => {
    console.log('the response will be sent by the next function ...');
    next();
  },
  (req: Request, res: Response) => {
    res.send('Hello from D!');
  }
);

Response methods

The methods on the response object (res) in the following table can send a response to the client, and terminate the request-response cycle. If none of these methods are called from a route handler, the client request will be left hanging.

MethodDescription
res.download()Prompt a file to be downloaded.
res.end()End the response process.
res.json()Send a JSON response.
res.jsonp()Send a JSON response with JSONP support.
res.redirect()Redirect a request.
res.render()Render a view template.
res.send()Send a response of various types.
res.sendFile()Send a file as an octet stream.
res.sendStatus()Set the response status code and send its string representation as the response body.

app.route()

You can create chainable route handlers for a route path by using app.route(). Because the path is specified in a single location, this helps to create modular routes and reduces redundancy and typos. For more information about routes, see the Router() documentation.

Here is an example of chained route handlers that are defined by using app.route().

js
app
  .route('/book')
  .get((req, res) => {
    res.send('Get a random book');
  })
  .post((req, res) => {
    res.send('Add a book');
  })
  .put((req, res) => {
    res.send('Update the book');
  });
ts

app
  .route('/book')
  .get((req: Request, res: Response) => {
    res.send('Get a random book');
  })
  .post((req: Request, res: Response) => {
    res.send('Add a book');
  })
  .put((req: Request, res: Response) => {
    res.send('Update the book');
  });

express.Router

Use the express.Router class to create modular, mountable route handlers. A Router instance is a complete middleware and routing system; for this reason, it is often referred to as a "mini-app".

The following example creates a router as a module, loads a middleware function in it, defines some routes, and mounts the router module on a path in the main app.

Create a router file named birds.js in the app directory, with the following content:

cjs title="birds.cjs"
const express = require('express');
const router = express.Router();

// middleware that is specific to this router
const timeLog = (req, res, next) => {
  console.log('Time: ', Date.now());
  next();
};
router.use(timeLog);

// define the home page route
router.get('/', (req, res) => {
  res.send('Birds home page');
});
// define the about route
router.get('/about', (req, res) => {
  res.send('About birds');
});

module.exports = router;
mjs title="birds.mjs"

const router = express.Router();

// middleware that is specific to this router
const timeLog = (req, res, next) => {
  console.log('Time: ', Date.now());
  next();
};
router.use(timeLog);

// define the home page route
router.get('/', (req, res) => {
  res.send('Birds home page');
});
// define the about route
router.get('/about', (req, res) => {
  res.send('About birds');
});
ts title="birds.ts"

const router = express.Router();

// middleware that is specific to this router
const timeLog = (req: Request, res: Response, next: NextFunction) => {
  console.log('Time: ', Date.now());
  next();
};
router.use(timeLog);

// define the home page route
router.get('/', (req: Request, res: Response) => {
  res.send('Birds home page');
});
// define the about route
router.get('/about', (req: Request, res: Response) => {
  res.send('About birds');
});

Then, load the router module in the app:

cjs title="index.cjs"
const birds = require('./birds');

// ...

app.use('/birds', birds);
mjs title="index.mjs"

// ...

app.use('/birds', birds);

The app will now be able to handle requests to /birds and /birds/about, as well as call the timeLog middleware function that is specific to the route.

But if the parent route /birds has path parameters, it will not be accessible by default from the sub-routes. To make it accessible, you will need to pass the mergeParams option to the Router constructor.

js
const router = express.Router({ mergeParams: true });

میان‌افزار

Express is a routing and middleware web framework with minimal functionality of its own: an Express application is essentially a series of middleware function calls executed during the request-response cycle.

_Middleware_ functions are functions that have access to:

  • The request object (req)
  • The response object (res)
  • The next middleware function in the application's request-response cycle, commonly named next

Middleware functions can perform the following tasks:

  • Execute any code.
  • Modify the request and response objects.
  • End the request-response cycle.
  • Pass control to the next middleware function.

If a middleware function does not end the request-response cycle, it must call next() to pass control to the next middleware function. Otherwise, the request will be left hanging.

An Express application can use the following types of middleware:

  • Application-level middleware
  • Router-level middleware
  • Error-handling middleware
  • Built-in middleware
  • Third-party middleware

You can load application-level and router-level middleware with an optional mount path. Multiple middleware functions can also be loaded together, which creates a middleware sub-stack at a mount point.

Application-level middleware

Bind application-level middleware to an instance of the app object by using the app.use() and app.METHOD() functions, where METHOD is the lowercase HTTP method of the request that the middleware function handles, such as get, post, put, or delete.

Middleware without a mount path

The following middleware function runs every time the app receives a request:

cjs title="index.cjs"
const express = require('express');
const app = express();

app.use((req, res, next) => {
  console.log('Time:', Date.now());
  next();
});
mjs title="index.mjs"

const app = express();

app.use((req, res, next) => {
  console.log('Time:', Date.now());
  next();
});
ts title="index.ts"

const app: Express = express();

app.use((req: Request, res: Response, next: NextFunction) => {
  console.log('Time:', Date.now());
  next();
});

Middleware mounted on a path

The following middleware function runs for any type of HTTP request on the /user/:id path:

js
app.use('/user/:id', (req, res, next) => {
  console.log('Request Type:', req.method);
  next();
});
ts

app.use('/user/:id', (req: Request, res: Response, next: NextFunction) => {
  console.log('Request Type:', req.method);
  next();
});

Route handlers

This example shows a route and its handler function (middleware system). The function handles GET requests to the /user/:id path:

js
app.get('/user/:id', (req, res) => {
  res.send('USER');
});
ts

app.get('/user/:id', (req: Request, res: Response) => {
  res.send('USER');
});

Middleware sub-stacks

Multiple middleware functions can be loaded together at a mount point to form a middleware sub-stack. This example prints request info for any type of HTTP request to the /user/:id path:

js
app.use(
  '/user/:id',
  (req, res, next) => {
    console.log('Request URL:', req.originalUrl);
    next();
  },
  (req, res, next) => {
    console.log('Request Type:', req.method);
    next();
  }
);
ts

app.use(
  '/user/:id',
  (req: Request, res: Response, next: NextFunction) => {
    console.log('Request URL:', req.originalUrl);
    next();
  },
  (req: Request, res: Response, next: NextFunction) => {
    console.log('Request Type:', req.method);
    next();
  }
);

Multiple route handlers

Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the /user/:id path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle.

js
app.get(
  '/user/:id',
  (req, res, next) => {
    console.log('ID:', req.params.id);
    next();
  },
  (req, res) => {
    res.send('User Info');
  }
);

// handler for the /user/:id path, which prints the user ID
app.get('/user/:id', (req, res) => {
  res.send(req.params.id);
});
ts

app.get(
  '/user/:id',
  (req: Request, res: Response, next: NextFunction) => {
    console.log('ID:', req.params.id);
    next();
  },
  (req: Request, res: Response) => {
    res.send('User Info');
  }
);

// handler for the /user/:id path, which prints the user ID
app.get('/user/:id', (req: Request, res: Response) => {
  res.send(req.params.id);
});

Skipping to the next route

Call next('route') to skip the remaining middleware functions in a router middleware stack and pass control to the next route.

<Alert type="info">

next('route') will work only in middleware functions that were loaded by using the app.METHOD() or router.METHOD() functions.

</Alert>

In the following example, if the user ID is 0, the first handler skips to the next route, which sends a special response:

js
app.get(
  '/user/:id',
  (req, res, next) => {
    // if the user ID is 0, skip to the next route
    if (req.params.id === '0') next('route');
    // otherwise pass the control to the next middleware function in this stack
    else next();
  },
  (req, res) => {
    // send a regular response
    res.send('regular');
  }
);

// handler for the /user/:id path, which sends a special response
app.get('/user/:id', (req, res) => {
  res.send('special');
});
ts

app.get(
  '/user/:id',
  (req: Request, res: Response, next: NextFunction) => {
    // if the user ID is 0, skip to the next route
    if (req.params.id === '0') next('route');
    // otherwise pass the control to the next middleware function in this stack
    else next();
  },
  (req: Request, res: Response) => {
    // send a regular response
    res.send('regular');
  }
);

// handler for the /user/:id path, which sends a special response
app.get('/user/:id', (req: Request, res: Response) => {
  res.send('special');
});

Reusable middleware arrays

Middleware functions can also be grouped into arrays for better reusability. This example shows an array with a middleware sub-stack that handles GET requests to the /user/:id path:

js
function logOriginalUrl(req, res, next) {
  console.log('Request URL:', req.originalUrl);
  next();
}

function logMethod(req, res, next) {
  console.log('Request Type:', req.method);
  next();
}

const logStuff = [logOriginalUrl, logMethod];
app.get('/user/:id', logStuff, (req, res) => {
  res.send('User Info');
});
ts

function logOriginalUrl(req: Request, res: Response, next: NextFunction) {
  console.log('Request URL:', req.originalUrl);
  next();
}

function logMethod(req: Request, res: Response, next: NextFunction) {
  console.log('Request Type:', req.method);
  next();
}

const logStuff = [logOriginalUrl, logMethod];
app.get('/user/:id', logStuff, (req: Request, res: Response) => {
  res.send('User Info');
});

Router-level middleware

Router-level middleware works the same way as application-level middleware, except it is bound to an instance of express.Router().

js
const router = express.Router();
ts

const router = express.Router();

Load router-level middleware by using the router.use() and router.METHOD() functions.

The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware:

cjs title="index.cjs"
const express = require('express');
const app = express();
const router = express.Router();

// a middleware function with no mount path. This code is executed for every request to the router
router.use((req, res, next) => {
  console.log('Time:', Date.now());
  next();
});

// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path
router.use(
  '/user/:id',
  (req, res, next) => {
    console.log('Request URL:', req.originalUrl);
    next();
  },
  (req, res, next) => {
    console.log('Request Type:', req.method);
    next();
  }
);

// a middleware sub-stack that handles GET requests to the /user/:id path
router.get(
  '/user/:id',
  (req, res, next) => {
    // if the user ID is 0, skip to the next route
    if (req.params.id === '0') next('route');
    // otherwise pass control to the next middleware function in this stack
    else next();
  },
  (req, res) => {
    // render a regular page
    res.render('regular');
  }
);

// handler for the /user/:id path, which renders a special page
router.get('/user/:id', (req, res) => {
  console.log(req.params.id);
  res.render('special');
});

// mount the router on the app
app.use('/', router);
mjs title="index.mjs"

const app = express();
const router = express.Router();

// a middleware function with no mount path. This code is executed for every request to the router
router.use((req, res, next) => {
  console.log('Time:', Date.now());
  next();
});

// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path
router.use(
  '/user/:id',
  (req, res, next) => {
    console.log('Request URL:', req.originalUrl);
    next();
  },
  (req, res, next) => {
    console.log('Request Type:', req.method);
    next();
  }
);

// a middleware sub-stack that handles GET requests to the /user/:id path
router.get(
  '/user/:id',
  (req, res, next) => {
    // if the user ID is 0, skip to the next route
    if (req.params.id === '0') next('route');
    // otherwise pass control to the next middleware function in this stack
    else next();
  },
  (req, res) => {
    // render a regular page
    res.render('regular');
  }
);

// handler for the /user/:id path, which renders a special page
router.get('/user/:id', (req, res) => {
  console.log(req.params.id);
  res.render('special');
});

// mount the router on the app
app.use('/', router);
ts title="index.ts"

const app: Express = express();
const router = express.Router();

// a middleware function with no mount path. This code is executed for every request to the router
router.use((req: Request, res: Response, next: NextFunction) => {
  console.log('Time:', Date.now());
  next();
});

// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path
router.use(
  '/user/:id',
  (req: Request, res: Response, next: NextFunction) => {
    console.log('Request URL:', req.originalUrl);
    next();
  },
  (req: Request, res: Response, next: NextFunction) => {
    console.log('Request Type:', req.method);
    next();
  }
);

// a middleware sub-stack that handles GET requests to the /user/:id path
router.get(
  '/user/:id',
  (req: Request, res: Response, next: NextFunction) => {
    // if the user ID is 0, skip to the next route
    if (req.params.id === '0') next('route');
    // otherwise pass control to the next middleware function in this stack
    else next();
  },
  (req: Request, res: Response) => {
    // render a regular page
    res.render('regular');
  }
);

// handler for the /user/:id path, which renders a special page
router.get('/user/:id', (req: Request, res: Response) => {
  console.log(req.params.id);
  res.render('special');
});

// mount the router on the app
app.use('/', router);

Skipping out of a router

Use next('router') to skip the rest of the router's middleware functions and pass control back out of the router instance.

In the following example, the router only responds when the request includes an x-auth header. Otherwise, next('router') exits the router and the app responds with a 401 status:

cjs title="index.cjs"
const express = require('express');
const app = express();
const router = express.Router();

// predicate the router with a check and bail out when needed
router.use((req, res, next) => {
  if (!req.headers['x-auth']) return next('router');
  next();
});

router.get('/user/:id', (req, res) => {
  res.send('hello, user!');
});

// use the router and 401 anything falling through
app.use('/admin', router, (req, res) => {
  res.sendStatus(401);
});
mjs title="index.mjs"

const app = express();
const router = express.Router();

// predicate the router with a check and bail out when needed
router.use((req, res, next) => {
  if (!req.headers['x-auth']) return next('router');
  next();
});

router.get('/user/:id', (req, res) => {
  res.send('hello, user!');
});

// use the router and 401 anything falling through
app.use('/admin', router, (req, res) => {
  res.sendStatus(401);
});
ts title="index.ts"

const app: Express = express();
const router = express.Router();

// predicate the router with a check and bail out when needed
router.use((req: Request, res: Response, next: NextFunction) => {
  if (!req.headers['x-auth']) return next('router');
  next();
});

router.get('/user/:id', (req: Request, res: Response) => {
  res.send('hello, user!');
});

// use the router and 401 anything falling through
app.use('/admin', router, (req: Request, res: Response) => {
  res.sendStatus(401);
});

Error-handling middleware

Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature (err, req, res, next):

js
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});
ts

app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});

<Alert type="alert">

Error-handling middleware always takes _four_ arguments. You must provide four arguments to identify it as an error-handling middleware function. Even if you don't need to use the next object, you must specify it to maintain the signature. Otherwise, the next object will be interpreted as regular middleware and will fail to handle errors.

</Alert>

<ReadMore>

For more information, see the Error handling guide.

</ReadMore>

Built-in middleware

Express has the following built-in middleware functions:

  • express.static serves static assets such as HTML files, images, and so on.
  • express.json parses incoming requests with JSON payloads.
  • express.raw parses incoming requests with Buffer payloads.
  • express.text parses incoming requests with text payloads.
  • express.urlencoded parses incoming requests with URL-encoded payloads.

Third-party middleware

Use third-party middleware to add functionality to Express apps.

Install the Node.js module for the required functionality, then load it in your app at the application level or at the router level.

The following example illustrates installing and loading the cookie-parsing middleware function cookie-parser:

<PackageManagerCommand command="npm install cookie-parser" />

cjs title="index.cjs"
const express = require('express');
const app = express();
const cookieParser = require('cookie-parser');

// load the cookie-parsing middleware
app.use(cookieParser());
mjs title="index.mjs"


const app = express();

// load the cookie-parsing middleware
app.use(cookieParser());
ts title="index.ts"


const app: Express = express();

// load the cookie-parsing middleware
app.use(cookieParser());

<ReadMore>

For a partial list of third-party middleware functions that are commonly used with Express, see the Third-party middleware page.

</ReadMore>