Objeto Application

El objeto app denota convencionalmente la aplicación Express. Créalo llamando a la función express() de nivel superior exportada por el módulo Express:

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

app.get('/', function (req, res) {
  res.send('hello world');
});

app.listen(3000);

import express from 'express';

const app = express();

app.get('/', function (req, res) {
  res.send('hello world');
});

app.listen(3000);

El objeto app tiene métodos para

• Enrutar peticiones HTTP; ver por ejemplo, app.METHOD y app.param.
• Configurar middleware; ver app.route.
• Renderizar vistas HTML; ver app.render.
• Registrar un motor de plantillas; ver app.engine.

También tiene configuraciones (propiedades) que afectan cómo se comporta la aplicación; para más información, consulta Configuración de la aplicación.

Propiedades

app.locals

El objeto app.locals tiene propiedades que son variables locales dentro de la aplicación, y estarán disponibles en las plantillas renderizadas con res.render.

console.dir(app.locals.title);
// => 'My App'

console.dir(app.locals.email);
// => 'me@myapp.com'

Una vez establecido, el valor de las propiedades de app.locals persiste durante toda la vida de la aplicación, en contraste con las propiedades de res.locals que son válidas solo durante la vida de la petición.

Puedes acceder a variables locales en las plantillas renderizadas dentro de la aplicación. Esto es útil para proporcionar funciones helper a las plantillas, así como datos a nivel de aplicación. Las variables locales están disponibles en el middleware vía req.app.locals (ver req.app)

app.locals.title = 'My App';
app.locals.strftime = require('strftime');
app.locals.email = 'me@myapp.com';

app.mountpath

La propiedad app.mountpath contiene uno o más patrones de ruta en los que se montó una sub-aplicación.

const express = require('express');

const app = express(); // the main app
const admin = express(); // the sub app

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

app.use('/admin', admin); // mount the sub app

import express from 'express';

const app = express(); // the main app
const admin = express(); // the sub app

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

app.use('/admin', admin); // mount the sub app

Es similar a la propiedad baseUrl del objeto req, excepto que req.baseUrl devuelve la ruta URL coincidente, en lugar de los patrones coincidentes.

Si una sub-aplicación está montada en múltiples patrones de ruta, app.mountpath devuelve la lista de patrones en los que está montada, como se muestra en el siguiente ejemplo.

const admin = express();

admin.get('/', (req, res) => {
  console.log(admin.mountpath); // [ '/adm{*splat}n', '/manager' ]
  res.send('Admin Homepage');
});

const secret = express();
secret.get('/', (req, res) => {
  console.log(secret.mountpath); // /secr{*splat}t
  res.send('Admin Secret');
});

admin.use('/secr{*splat}t', secret); // load the 'secret' router on '/secr{*splat}t', on the 'admin' sub app
app.use(['/adm{*splat}n', '/manager'], admin); // load the 'admin' router on '/adm{*splat}n' and '/manager', on the parent app

app.router

La instancia integrada de router de la aplicación. Se crea de forma diferida, en el primer acceso.

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

router.get('/', (req, res) => {
  res.send('hello world');
});

app.listen(3000);

import express from 'express';

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

router.get('/', (req, res) => {
  res.send('hello world');
});

app.listen(3000);

Puedes añadir middleware y rutas de métodos HTTP al router al igual que a una aplicación.

Para más información, ver Router.

Eventos

app.on(‘mount’)

El evento mount se dispara en una sub-aplicación cuando se monta en una aplicación padre. La aplicación padre se pasa a la función callback.

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

Métodos

app.all()

Este método es como los métodos estándar app.METHOD(), excepto que coincide con todos los verbos HTTP.

Ejemplos

El siguiente callback se ejecuta para peticiones a /secret ya sea usando GET, POST, PUT, DELETE, o cualquier otro método de petición HTTP:

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

El método app.all() es útil para mapear lógica “global” para prefijos de ruta específicos o coincidencias arbitrarias. Por ejemplo, si pones lo siguiente al principio de todas las demás definiciones de rutas, requiere que todas las rutas desde ese punto requieran autenticación, y automáticamente cargue un usuario. Ten en mente que estos callbacks no tienen que actuar como endpoints: loadUser puede realizar una tarea, y luego llamar next() para continuar coincidiendo rutas subsiguientes.

app.all('{*splat}', requireAuthentication, loadUser);

O el equivalente:

app.all('{*splat}', requireAuthentication);
app.all('{*splat}', loadUser);

Otro ejemplo es funcionalidad “global” con lista blanca. El ejemplo es similar a los anteriores, pero solo restringe rutas que empiezan con “/api”:

app.all('/api/{*splat}', requireAuthentication);

app.delete()

Dirige las peticiones HTTP DELETE a la ruta especificada con las funciones callback indicadas. Para más información, ver la guía de enrutamiento.

Ejemplo

app.delete('/', (req, res) => {
  res.send('DELETE request to homepage');
});

app.disable()

Establece la configuración Boolean name a false, donde name es una de las propiedades de la tabla de configuraciones de app. Llamar a app.set('foo', false) para una propiedad Boolean es lo mismo que llamar a app.disable('foo').

Por ejemplo:

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

app.disabled()

Devuelve true si la configuración Boolean name está desactivada (false), donde name es una de las propiedades de la tabla de configuraciones de app.

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

app.enable('trust proxy');
app.disabled('trust proxy');
// => false

app.enable()

Establece la configuración Boolean name a true, donde name es una de las propiedades de la tabla de configuraciones de app. Llamar a app.set('foo', true) para una propiedad Boolean es lo mismo que llamar a app.enable('foo').

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

app.enabled()

Devuelve true si la configuración name está activada (true), donde name es una de las propiedades de la tabla de configuraciones de app.

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

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

app.engine()

Registra el callback del motor de plantillas dado como ext.

Por defecto, Express hará require() del motor basándose en la extensión del archivo. Por ejemplo, si intentas renderizar un archivo “foo.pug”, Express invoca lo siguiente internamente, y cachea el require() en llamadas subsiguientes para aumentar el rendimiento.

app.engine('pug', require('pug').__express);

Usa este método para motores que no proporcionan .__express por defecto, o si deseas “mapear” una extensión diferente al motor de plantillas.

Por ejemplo, para mapear el motor de plantillas EJS a archivos “.html”:

app.engine('html', require('ejs').renderFile);

En este caso, EJS proporciona un método .renderFile() con la misma firma que Express espera: (path, options, callback), aunque ten en cuenta que internamente hace alias de este método como ejs.__express así que si estás usando extensiones “.ejs” no necesitas hacer nada.

Algunos motores de plantillas no siguen esta convención. La librería consolidate.js mapea motores de plantillas de Node para seguir esta convención, para que funcionen sin problemas con Express.

const engines = require('consolidate');
app.engine('haml', engines.haml);
app.engine('html', engines.hogan);

import engines from 'consolidate';

app.engine('haml', engines.haml);
app.engine('html', engines.hogan);

app.get(name)

Devuelve el valor de la configuración de app name, donde name es uno de los strings en la tabla de configuraciones de app. Por ejemplo:

app.get('title');
// => undefined

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

app.get()

Dirige las peticiones HTTP GET a la ruta especificada con las funciones callback indicadas.

Para más información, ver la guía de enrutamiento.

Ejemplo

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

app.listen()

Vincula y escucha conexiones en el host y puerto especificados, o inicia un socket UNIX y escucha conexiones en la ruta dada. Este método es idéntico al http.Server.listen() de Node.

Si se omite el puerto o es 0, el sistema operativo asignará un puerto arbitrario no usado, lo cual es útil para casos como tareas automatizadas (tests, etc.).

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

app.listen(3000); // bind and listen on a TCP port
app.listen('/tmp/sock'); // or listen on a UNIX socket

import express from 'express';

const app = express();

app.listen(3000); // bind and listen on a TCP port
app.listen('/tmp/sock'); // or listen on a UNIX socket

const server = app.listen(8080, '0.0.0.0', (error) => {
  if (error) {
    throw error; // e.g. EADDRINUSE
  }
  console.log(`Listening on ${JSON.stringify(server.address())}`);
});

El app devuelto por express() es de hecho una Function de JavaScript, diseñada para pasarse a los servidores HTTP de Node como callback para manejar peticiones. Esto hace fácil proporcionar versiones HTTP y HTTPS de tu aplicación con la misma base de código, ya que la aplicación no hereda de estos (es simplemente un callback):

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

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

import express from 'express';
import https from 'https';
import http from 'http';

const app = express();

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

El método app.listen() devuelve un objeto http.Server y (para HTTP) es un método de conveniencia para lo siguiente:

app.listen = function () {
  const server = http.createServer(this);
  return server.listen.apply(server, arguments);
};

app.METHOD()

Dirige una petición HTTP, donde METHOD es el método HTTP de la petición, como GET, PUT, POST, y así sucesivamente, en minúsculas. Así, los métodos reales son app.get(), app.post(), app.put(), y así sucesivamente. Ver Métodos de enrutamiento más abajo para la lista completa.

Métodos de enrutamiento

Express soporta los siguientes métodos de enrutamiento correspondientes a los métodos HTTP con los mismos nombres:

La documentación de la API tiene entradas explícitas solo para los métodos HTTP más populares app.get(), app.post(), app.put(), app.delete(), y app.query(). Sin embargo, los otros métodos listados arriba funcionan exactamente de la misma manera.

Para enrutar métodos que se traducen a nombres de variables JavaScript inválidos, usa la notación con corchetes. Por ejemplo, app['m-search']('/', function ....

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

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

// methods that are invalid JavaScript variable names use bracket notation
app['m-search']('/', (req, res) => {
  res.send('M-SEARCH request to homepage');
});

El método, app.all(), no se deriva de ningún método HTTP y carga middleware en la ruta especificada para todos los métodos de petición HTTP. Para más información, ver app.all.

Para más información sobre enrutamiento, ver la guía de enrutamiento.

app.param()

Añade triggers callback a los parámetros de ruta, donde name es el nombre del parámetro o un array de ellos, y callback es la función callback. Los parámetros de la función callback son el objeto request, el objeto response, el siguiente middleware, el valor del parámetro y el nombre del parámetro, en ese orden.

Si name es un array, el trigger callback se registra para cada parámetro declarado en él, en el orden en que se declaran. Además, para cada parámetro declarado excepto el último, una llamada a next dentro del callback llamará al callback del siguiente parámetro declarado. Para el último parámetro, una llamada a next llamará al siguiente middleware en su lugar para la ruta que se está procesando actualmente, tal como lo haría si name fuera solo un string.

Por ejemplo, cuando :user está presente en una ruta, puedes mapear lógica de carga de usuario para proporcionar automáticamente req.user a la ruta, o realizar validaciones sobre la entrada del parámetro.

app.param('user', (req, res, next, id) => {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, (err, user) => {
    if (err) {
      next(err);
    } else if (user) {
      req.user = user;
      next();
    } else {
      next(new Error('failed to load user'));
    }
  });
});

Las funciones callback de parámetros son locales al router en el que se definen. No son heredadas por apps o routers montados, ni se disparan para parámetros de ruta heredados de routers padre. Por lo tanto, los callbacks de parámetros definidos en app solo se dispararán por parámetros de ruta definidos en rutas de app.

Todos los callbacks de parámetros se llamarán antes que cualquier handler de cualquier ruta en la que el parámetro aparezca, y cada uno se llamará solo una vez por ciclo petición-respuesta, incluso si el parámetro coincide en múltiples rutas, como se muestra en los siguientes ejemplos.

app.param('id', (req, res, next, id) => {
  console.log('CALLED ONLY ONCE');
  next();
});

app.get('/user/:id', (req, res, next) => {
  console.log('although this matches');
  next();
});

app.get('/user/:id', (req, res) => {
  console.log('and this matches too');
  res.end();
});

En GET /user/42, se imprime lo siguiente:

CALLED ONLY ONCE
although this matches
and this matches too

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

app.get('/user/:id/:page', (req, res, next) => {
  console.log('although this matches');
  next();
});

app.get('/user/:id/:page', (req, res) => {
  console.log('and this matches too');
  res.end();
});

En GET /user/42/3, se imprime lo siguiente:

CALLED ONLY ONCE with 42
CALLED ONLY ONCE with 3
although this matches
and this matches too

app.path()

Devuelve la ruta canónica de la aplicación, un string.

const app = express();
const blog = express();
const blogAdmin = express();

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

console.log(app.path()); // ''
console.log(blog.path()); // '/blog'
console.log(blogAdmin.path()); // '/blog/admin'

El comportamiento de este método puede volverse muy complicado en casos complejos de apps montadas: es usualmente mejor usar req.baseUrl para obtener la ruta canónica de la aplicación.

app.post()

Dirige las peticiones HTTP POST a la ruta especificada con las funciones callback indicadas. Para más información, ver la guía de enrutamiento.

Ejemplo

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

app.put()

Dirige las peticiones HTTP PUT a la ruta especificada con las funciones callback indicadas.

Ejemplo

app.put('/', (req, res) => {
  res.send('PUT request to homepage');
});

app.query()

Dirige las peticiones HTTP QUERY a la ruta especificada con las funciones callback indicadas. Para más información, ver la guía de enrutamiento.

El método HTTP QUERY (RFC 10008) está diseñado para consultas cuya entrada es demasiado grande o sensible para codificar en la URL. A diferencia de GET, una petición QUERY lleva un body que contiene la entrada de la consulta. A diferencia de POST, es explícitamente seguro e idempotente, los intermediarios y caches pueden reintentarlo automáticamente, y la respuesta es cacheable (con el body de la petición incluido en la clave de cache).

Usa app.query() cuando los parámetros de consulta excedan los límites de longitud de URL, contengan datos sensibles que no deberían aparecer en logs del servidor o historial del navegador, o sean demasiado complejos para expresar limpiamente como una cadena de consulta URL, como filtros profundamente anidados o criterios estructurados.

Como la entrada de la consulta viaja en el body de la petición, req.body es undefined hasta que montas un middleware de body-parsing como express.json() o express.urlencoded() que coincida con el Content-Type de la petición.

Ejemplo

app.use(express.json()); // populate req.body for application/json payloads

app.query('/search', (req, res) => {
  // complex filter criteria arrive in req.body, not the URL
  const results = db.search(req.body);
  res.json(results);
});

app.render()

Devuelve el HTML renderizado de una vista vía la función callback. Acepta un parámetro opcional que es un objeto que contiene variables locales para la vista. Es como res.render(), excepto que no puede enviar por sí solo la vista renderizada al cliente.

app.render('email', (err, html) => {
  // ...
});

app.render('email', { name: 'Tobi' }, (err, html) => {
  // ...
});

app.route()

Devuelve una instancia de una única ruta, que luego puedes usar para manejar verbos HTTP con middleware opcional. Usa app.route() para evitar nombres de ruta duplicados (y por tanto errores tipográficos).

const app = express();

app
  .route('/events')
  .all((req, res, next) => {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
  })
  .get((req, res, next) => {
    res.json({});
  })
  .post((req, res, next) => {
    // maybe add a new event...
  });

app.set()

Asigna la configuración name al value. Puedes almacenar cualquier valor que desees, pero ciertos nombres se pueden usar para configurar el comportamiento del servidor. Estos nombres especiales están listados en la tabla de configuraciones de app.

Llamar a app.set('foo', true) para una propiedad Boolean es lo mismo que llamar a app.enable('foo'). De forma similar, llamar a app.set('foo', false) para una propiedad Boolean es lo mismo que llamar a app.disable('foo').

Recupera el valor de una configuración con app.get().

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

Configuraciones de la aplicación

La siguiente tabla lista las configuraciones de la aplicación.

Opciones para la configuración trust proxy

Lee Express detrás de proxies para más información.

Boolean: Si es true, la dirección IP del cliente se entiende como la entrada más a la izquierda en el header X-Forwarded-*. Si es false, la aplicación se entiende como directamente enfrentada a Internet y la dirección IP del cliente se deriva de req.connection.remoteAddress. Esta es la configuración por defecto.

String / String que contiene valores separados por comas / Array de strings: Una dirección IP, subred, o un array de direcciones IP y subredes en las que confiar. Los nombres de subredes preconfigurados son:

• loopback - 127.0.0.1/8, ::1/128
• linklocal - 169.254.0.0/16, fe80::/10
• uniquelocal - 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7

Establece direcciones IP de cualquiera de las siguientes formas:

Especifica una única subred:

app.set('trust proxy', 'loopback');

Especifica una subred y una dirección:

app.set('trust proxy', 'loopback, 123.123.123.123');

Especifica múltiples subredes como CSV:

app.set('trust proxy', 'loopback, linklocal, uniquelocal');

Especifica múltiples subredes como un array:

app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']);

Cuando se especifica, las direcciones IP o las subredes se excluyen del proceso de determinación de direcciones, y la dirección IP no confiable más cercana al servidor de la aplicación se determina como la dirección IP del cliente.

Number: Confía en el n-ésimo salto desde el servidor proxy frontal como cliente.

Function: Implementación personalizada de confianza. Usa esto solo si sabes lo que estás haciendo.

app.set('trust proxy', (ip) => {
  if (ip === '127.0.0.1' || ip === '123.123.123.123')
    return true; // trusted IPs
  else return false;
});

Opciones para la configuración etag

La funcionalidad ETag está implementada usando el paquete etag. Para más información, ver su documentación.

app.set('etag', (body, encoding) => {
  return generateHash(body, encoding); // consider the function is defined
});

app.use()

Monta la función o funciones de middleware especificadas en la ruta especificada: la función middleware se ejecuta cuando la base de la ruta de la petición coincide con path.

Descripción

Una ruta coincidirá con cualquier ruta que siga inmediatamente a su ruta con un “/”. Por ejemplo: app.use('/apple', ...) coincidirá con “/apple”, “/apple/images”, “/apple/images/news”, y así sucesivamente.

Como path es por defecto ”/”, el middleware montado sin una ruta se ejecutará para cada petición a la aplicación. Por ejemplo, esta función middleware se ejecutará para cada petición a la aplicación:

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

Las funciones middleware se ejecutan secuencialmente, por lo tanto el orden de inclusión del middleware es importante.

// this middleware will not allow the request to go beyond it
app.use((req, res, next) => {
  res.send('Hello World');
});

// requests will never reach this route
app.get('/', (req, res) => {
  res.send('Welcome');
});

Error-handling middleware

El middleware de manejo de errores siempre toma cuatro argumentos. Debes proporcionar cuatro argumentos para identificarlo como una función middleware de manejo de errores. Incluso si no necesitas usar el objeto next, debes especificarlo para mantener la firma. De lo contrario, el objeto next será interpretado como middleware regular y no podrá manejar errores. Para más detalles sobre middleware de manejo de errores, ver: Manejo de errores.

Define las funciones middleware de manejo de errores de la misma manera que otras funciones middleware, excepto con cuatro argumentos en lugar de tres, específicamente con la firma (err, req, res, next)):

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

Ejemplos de rutas

La siguiente tabla proporciona algunos ejemplos simples de valores válidos de path para montar middleware.

Ruta: Coincide con la ruta exacta /abcd y cualquier sub-ruta que empiece con /abcd/ (por ejemplo, /abcd/foo):

app.use('/abcd', (req, res, next) => {
  next();
});

Patrón de ruta: Esto coincidirá con rutas que empiezan con /abcd y /abd:

app.use('/ab{c}d', (req, res, next) => {
  next();
});

Expresión regular: Esto coincidirá con rutas que empiezan con /abc y /xyz:

app.use(/\/abc|\/xyz/, (req, res, next) => {
  next();
});

Array: Esto coincidirá con rutas que empiezan con /abcd, /xyza, /lmn, y /pqr:

app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], (req, res, next) => {
  next();
});

Ejemplos de funciones callback middleware

La siguiente tabla proporciona algunos ejemplos simples de funciones middleware que pueden usarse como el argumento callback de app.use(), app.METHOD(), y app.all().

Middleware único: Puedes definir y montar una función middleware localmente.

app.use((req, res, next) => {
  next();
});

Un router es middleware válido.

const router = express.Router();
router.get('/', (req, res, next) => {
  next();
});
app.use(router);

Una aplicación Express es middleware válido.

const subApp = express();
subApp.get('/', (req, res, next) => {
  next();
});
app.use(subApp);

Serie de middleware: Puedes especificar más de una función middleware en la misma ruta de montaje.

const r1 = express.Router();
r1.get('/', (req, res, next) => {
  next();
});

const r2 = express.Router();
r2.get('/', (req, res, next) => {
  next();
});

app.use(r1, r2);

Array: Usa un array para agrupar middleware lógicamente.

const r1 = express.Router();
r1.get('/', (req, res, next) => {
  next();
});

const r2 = express.Router();
r2.get('/', (req, res, next) => {
  next();
});

app.use([r1, r2]);

Combinación: Puedes combinar todas las formas anteriores de montar middleware.

function mw1(req, res, next) {
  next();
}
function mw2(req, res, next) {
  next();
}

const r1 = express.Router();
r1.get('/', (req, res, next) => {
  next();
});

const r2 = express.Router();
r2.get('/', (req, res, next) => {
  next();
});

const subApp = express();
subApp.get('/', (req, res, next) => {
  next();
});

app.use(mw1, [mw2, r1, r2], subApp);

A continuación hay algunos ejemplos de uso del middleware express.static en una aplicación Express.

Sirve contenido estático para la aplicación desde el directorio “public” en el directorio de la aplicación:

// GET /style.css etc
app.use(express.static(path.join(__dirname, 'public')));

Monta el middleware en “/static” para servir contenido estático solo cuando la ruta de la petición tiene el prefijo “/static”:

// GET /static/style.css etc.
app.use('/static', express.static(path.join(__dirname, 'public')));

Desactiva el logging de peticiones de contenido estático cargando el middleware logger después del middleware estático:

app.use(express.static(path.join(__dirname, 'public')));
app.use(logger());

Sirve archivos estáticos desde múltiples directorios, pero dale prioridad a ”./public” sobre los demás:

app.use(express.static(path.join(__dirname, 'public')));
app.use(express.static(path.join(__dirname, 'files')));
app.use(express.static(path.join(__dirname, 'uploads')));