Application

Overview

The app object is the Express application. It’s created by calling express() and represents the top-level of your application.

const express = require('express');
const app = express();

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

app.listen(3000);

Properties

app.locals

Local variables scoped to the application. These variables are available within the application and are useful for providing helper functions or application-level data to templates.

app.locals.title = 'My App';
app.locals.email = '[email protected]';

app.locals properties persist throughout the life of the application, unlike res.locals which are scoped to the request.

app.mountpath

Contains the path pattern(s) on which a sub-app was mounted.

const admin = express();
admin.get('/', (req, res) => {
  console.log(admin.mountpath); // '/admin'
  res.send('Admin Homepage');
});

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

Settings Methods

app.set(setting, value)

Assigns value to the application setting setting. When called with only one argument, returns the setting’s value.

setting

string

required

The name of the setting

value

any

The value to assign to the setting

app.set('title', 'My Site');
app.get('title'); // => "My Site"

app.set('views', './views');
app.set('view engine', 'ejs');

Common Settings:

View Settings
Network Settings
Response Settings
Other Settings

views - Directory for view templates (default: process.cwd() + '/views')
view engine - Default template engine extension
view cache - Enables view template compilation caching (enabled in production)

trust proxy - Indicates the app is behind a proxy and to trust X-Forwarded-* headers
subdomain offset - Number of dot-separated parts to remove to access subdomain (default: 2)

etag - Set ETag response header. Values: 'weak', 'strong', false (default: 'weak')
jsonp callback name - JSONP callback name (default: 'callback')
json spaces - JSON response spaces for formatting
json replacer - JSON replacer callback
json escape - Escape JSON responses for security

query parser - Query string parser. Values: 'simple', 'extended', false, or custom function (default: 'simple')
x-powered-by - Enable/disable X-Powered-By header (default: true)
env - Environment mode (default: process.env.NODE_ENV or 'development')

app.get(setting)

Returns the value of the application setting setting.

setting

string

required

The name of the setting to retrieve

app.get('title'); // => undefined
app.set('title', 'My Site');
app.get('title'); // => "My Site"

app.enable(setting)

Sets the boolean setting setting to true.

setting

string

required

The name of the setting to enable

app.enable('trust proxy');
app.get('trust proxy'); // => true

app.disable(setting)

Sets the boolean setting setting to false.

setting

string

required

The name of the setting to disable

app.disable('trust proxy');
app.get('trust proxy'); // => false

app.enabled(setting)

Returns true if the setting setting is enabled (truthy).

setting

string

required

The name of the setting to check

app.enable('trust proxy');
app.enabled('trust proxy'); // => true

app.disabled(setting)

Returns true if the setting setting is disabled (falsy).

setting

string

required

The name of the setting to check

app.disable('trust proxy');
app.disabled('trust proxy'); // => true

Middleware & Routing Methods

app.use([path], …callbacks)

Mounts middleware function(s) at the specified path. The middleware function is executed when the base of the requested path matches path.

path

string

default:"/"

The path for which the middleware is invoked

callbacks

function | array

required

Middleware function(s) or an array of middleware functions

// Middleware with no mount path - executed for every request
app.use((req, res, next) => {
  console.log('Time:', Date.now());
  next();
});

// Middleware mounted on /user/:id - executed for any type of HTTP request on /user/:id
app.use('/user/:id', (req, res, next) => {
  console.log('Request Type:', req.method);
  next();
});

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

// Array of middleware
const middleware = [fn1, fn2, fn3];
app.use('/admin', middleware);

Middleware functions must call next() to pass control to the next middleware function. Otherwise, the request will be left hanging.

app.route(path)

Returns an instance of a single route which you can then use to handle HTTP verbs with optional middleware. Use app.route() to avoid duplicate route naming and thus typing errors.

path

string

required

The path for the route

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

HTTP Method Routes

Express supports the following routing methods corresponding to HTTP methods:

app.get(path, ...callbacks)
app.post(path, ...callbacks)
app.put(path, ...callbacks)
app.delete(path, ...callbacks)
app.patch(path, ...callbacks)
app.head(path, ...callbacks)
app.options(path, ...callbacks)

And more. See the Routing guide for details.

path

string

required

The path for which the handler is invoked

callbacks

function

required

Callback function(s) to handle the request

GET
POST
PUT
DELETE

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

app.post('/user', (req, res) => {
  res.send('User created');
});

app.put('/user/:id', (req, res) => {
  res.send(`Update user ${req.params.id}`);
});

app.delete('/user/:id', (req, res) => {
  res.send(`Delete user ${req.params.id}`);
});

app.all(path, …callbacks)

Matches all HTTP methods on the specified path. Useful for defining middleware that applies to all HTTP verbs.

path

string

required

The path for which the handler is invoked

callbacks

function

required

Callback function(s) to handle the request

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

app.all('*', (req, res) => {
  res.status(404).send('404 Not Found');
});

app.param(name, callback)

Adds callback triggers to route parameters. The name parameter can be a single parameter name or an array of parameter names.

name

string | array

required

The name(s) of the route parameter(s)

callback

function

required

The callback function with signature (req, res, next, value, name)

app.param('user', (req, res, next, id) => {
  // Load user from database
  User.find(id, (err, user) => {
    if (err) {
      next(err);
    } else if (user) {
      req.user = user;
      next();
    } else {
      next(new Error('failed to load user'));
    }
  });
});

app.get('/user/:user', (req, res) => {
  res.send(`User: ${req.user.name}`);
});

// Array of parameter names
app.param(['id', 'page'], (req, res, next, value) => {
  console.log('CALLED ONLY ONCE with', value);
  next();
});

View Rendering

app.render(view, [options], callback)

Renders a view with a callback. Accepts an optional options object. This is used internally by res.render().

view

string

required

The name of the view file to render

options

object

An object whose properties define local variables for the view

callback

function

required

Callback function with signature (err, html)

app.render('email', { name: 'Tobi' }, (err, html) => {
  if (err) {
    console.error(err);
    return;
  }
  // html contains the rendered output
  console.log(html);
});

app.engine(ext, callback)

Registers the given template engine callback as ext.

ext

string

required

The file extension (with or without leading dot)

callback

function

required

The template engine function with signature (path, options, callback)

const ejs = require('ejs');

// Map .html files to ejs engine
app.engine('html', ejs.renderFile);
app.set('view engine', 'html');

// Use consolidate.js for other engines
const engines = require('consolidate');
app.engine('hbs', engines.handlebars);
app.engine('pug', engines.pug);

Express will require() the engine internally if it provides a .__express method. For engines without this method, use this function to map extensions.

Server Methods

app.listen([port], [hostname], [backlog], [callback])

Starts the application and binds it to a port. This method is identical to Node.js’s http.Server.listen().

port

number

The port number to listen on (default: 3000)

hostname

string

The hostname to bind to

backlog

number

The maximum length of the queue of pending connections

callback

function

Callback function called once the server starts listening

const express = require('express');
const app = express();

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

// Listen on specific host and port
app.listen(3000, 'localhost', () => {
  console.log('Server listening on localhost:3000');
});

The app.listen() method returns an http.Server object:

const server = app.listen(3000);

// Can be used for graceful shutdown
process.on('SIGTERM', () => {
  server.close(() => {
    console.log('Server closed');
  });
});

If you want to create both HTTP and HTTPS servers, use the Node.js http and https modules directly:

const http = require('http');
const https = require('https');
const express = require('express');
const app = express();

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

Events

mount

The mount event is fired on a sub-app when it’s mounted on a parent app. The parent app is passed to the callback function.

const admin = express();

admin.on('mount', (parent) => {
  console.log('Admin Mounted');
  console.log(parent); // refers to the parent app
});

admin.get('/', (req, res) => {
  res.send('Admin Homepage');
});

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

Getting Started

Core Concepts

Guides

Advanced

Overview

Properties

app.locals

app.mountpath

Settings Methods

app.set(setting, value)

app.get(setting)

app.enable(setting)

app.disable(setting)

app.enabled(setting)

app.disabled(setting)

Middleware & Routing Methods

app.use([path], …callbacks)

app.route(path)

HTTP Method Routes

app.all(path, …callbacks)

app.param(name, callback)

View Rendering

app.render(view, [options], callback)

app.engine(ext, callback)

Server Methods

app.listen([port], [hostname], [backlog], [callback])

Events

mount

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Advanced

​Overview

​Properties

​app.locals

​app.mountpath

​Settings Methods

​app.set(setting, value)

​app.get(setting)

​app.enable(setting)

​app.disable(setting)

​app.enabled(setting)

​app.disabled(setting)

​Middleware & Routing Methods

​app.use([path], …callbacks)

​app.route(path)

​HTTP Method Routes

​app.all(path, …callbacks)

​app.param(name, callback)

​View Rendering

​app.render(view, [options], callback)

​app.engine(ext, callback)

​Server Methods

​app.listen([port], [hostname], [backlog], [callback])

​Events

​mount

Build docs developers (and LLMs) love

Overview

Properties

app.locals

app.mountpath

Settings Methods

app.set(setting, value)

app.get(setting)

app.enable(setting)

app.disable(setting)

app.enabled(setting)

app.disabled(setting)

Middleware & Routing Methods

app.use([path], …callbacks)

app.route(path)

HTTP Method Routes

app.all(path, …callbacks)

app.param(name, callback)

View Rendering

app.render(view, [options], callback)

app.engine(ext, callback)

Server Methods

app.listen([port], [hostname], [backlog], [callback])

Events

mount