Objeto Express

Crea una aplicación Express. La función express() es una función de nivel superior exportada por el módulo express.

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

Métodos

El objeto Express tiene los siguientes métodos que pueden usarse para crear funciones de middleware, routers y tiene algo de middleware integrado:

express.json()

Argumentos

options

Tipo: Object | undefined

Configura cómo se parsea el body JSON; acepta las propiedades siguientes.

defaultCharset

Tipo: String Por defecto: "utf-8"

Especifica el conjunto de caracteres predeterminado para el contenido JSON si el charset no se especifica en el encabezado Content-Type de la petición.

inflate

Tipo: Boolean Por defecto: true

Activa o desactiva el manejo de bodies deflados (comprimidos); cuando está desactivado, los bodies deflados son rechazados.

limit

Tipo: Number | String Por defecto: "100kb"

Controla el tamaño máximo del body de la petición. Si es un número, entonces el valor especifica el número de bytes; si es un string, el valor se pasa a la librería bytes para su parseo.

reviver

Tipo: Function Por defecto: null

La opción reviver se pasa directamente a JSON.parse como segundo argumento. Puedes encontrar más información sobre este argumento en la documentación de MDN sobre JSON.parse.

strict

Tipo: Boolean Por defecto: true

Activa o desactiva aceptar solo arrays y objetos; cuando está desactivado aceptará cualquier cosa que JSON.parse acepte.

type

Tipo: String | String[] | Function Por defecto: "application/json"

Esto se usa para determinar qué tipo de media parseará el middleware. Esta opción puede ser un string, un array de strings, o una función. Si no es una función, la opción type se pasa directamente a la librería type-is y esto puede ser un nombre de extensión (como json), un tipo mime (como application/json), o un tipo mime con un comodín (como */* o */json). Si es una función, la opción type se llama como fn(req) y la petición se parsea si devuelve un valor truthy.

verify

Tipo: Function Por defecto: undefined

Esta opción, si se proporciona, se llama como verify(req, res, buf, encoding), donde buf es un Buffer del body raw de la petición y encoding es la codificación de la petición. El parseo se puede abortar lanzando un error.

Esta es una función middleware integrada en Express. Parsea las peticiones entrantes con payloads JSON y está basada en body-parser.

Devuelve middleware que solo parsea JSON y solo mira las peticiones donde el header Content-Type coincide con la opción type. Este parser acepta cualquier codificación Unicode del body y soporta la inflación automática de las codificaciones gzip y deflate.

Advertencia

Como la forma de req.body está basada en entrada controlada por el usuario, todas las propiedades y valores en este objeto son no confiables y deberían validarse antes de confiar en ellos. Por ejemplo, req.body.foo.toString() puede fallar de múltiples maneras, por ejemplo foo puede no estar ahí o puede no ser un string, y toString puede no ser una función y en su lugar un string u otra entrada del usuario.

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

// parse requests with a Content-Type of application/json
app.use(express.json());

app.post('/profile', (req, res) => {
  console.dir(req.body);
  res.json(req.body);
});

import express from 'express';

const app = express();

// parse requests with a Content-Type of application/json
app.use(express.json());

app.post('/profile', (req, res) => {
  console.dir(req.body);
  res.json(req.body);
});

express.raw()

Argumentos

options

Tipo: Object | undefined

Configura cómo se parsea el body de la petición; acepta las propiedades siguientes.

inflate

Tipo: Boolean Por defecto: true

Activa o desactiva el manejo de bodies deflados (comprimidos); cuando está desactivado, los bodies deflados son rechazados.

limit

Tipo: Number | String Por defecto: "100kb"

Controla el tamaño máximo del body de la petición. Si es un número, entonces el valor especifica el número de bytes; si es un string, el valor se pasa a la librería bytes para su parseo.

type

Tipo: String | String[] | Function Por defecto: "application/octet-stream"

Esto se usa para determinar qué tipo de media parseará el middleware. Esta opción puede ser un string, un array de strings, o una función. Si no es una función, la opción type se pasa directamente a la librería type-is y esto puede ser un nombre de extensión (como bin), un tipo mime (como application/octet-stream), o un tipo mime con un comodín (como */* o application/*). Si es una función, la opción type se llama como fn(req) y la petición se parsea si devuelve un valor truthy.

verify

Tipo: Function Por defecto: undefined

Esta es una función middleware integrada en Express. Parsea los payloads de las peticiones entrantes en un Buffer y está basada en body-parser.

Devuelve middleware que parsea todos los bodies como un Buffer y solo mira las peticiones donde el header Content-Type coincide con la opción type. Este parser acepta cualquier codificación Unicode del body y soporta la inflación automática de las codificaciones gzip y deflate.

Un nuevo body Buffer que contiene los datos analizados se popula en el objeto request después del middleware (es decir, req.body), o undefined si no había body que analizar, el Content-Type no coincidió, o ocurrió un error.

Advertencia

Como la forma de req.body está basada en entrada controlada por el usuario, todas las propiedades y valores en este objeto son no confiables y deberían validarse antes de confiar en ellos. Por ejemplo, req.body.toString() puede fallar de múltiples maneras, por ejemplo al apilar múltiples parsers req.body puede ser de un parser diferente. Se recomienda comprobar que req.body es un Buffer antes de llamar métodos de buffer.

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

// parse requests with a Content-Type of application/octet-stream into a Buffer
app.use(express.raw());

app.post('/upload', (req, res) => {
  console.dir(Buffer.isBuffer(req.body)); // => true
  res.send(`received ${req.body.length} bytes`);
});

import express from 'express';

const app = express();

// parse requests with a Content-Type of application/octet-stream into a Buffer
app.use(express.raw());

app.post('/upload', (req, res) => {
  console.dir(Buffer.isBuffer(req.body)); // => true
  res.send(`received ${req.body.length} bytes`);
});

express.Router()

Argumentos

caseSensitive

Tipo: Boolean Por defecto: false

Activa la sensibilidad a mayúsculas/minúsculas. Desactivado por defecto, tratando /Foo y /foo como iguales.

mergeParams

Tipo: Boolean Por defecto: false

Preserva los valores de req.params del router padre. Si el padre y el hijo tienen nombres de parámetros en conflicto, el valor del hijo tiene precedencia.

strict

Tipo: Boolean Por defecto: false

Activa el enrutamiento estricto. Desactivado por defecto, /foo y /foo/ son tratados igual por el router.

Crea un nuevo objeto router.

const router = express.Router([options]);

Puedes añadir middleware y rutas de métodos HTTP (como get, put, post, y así sucesivamente) al router igual que en una aplicación.

Para más información, ver Router.

express.static()

Argumentos

root

Tipo: String

El directorio raíz desde el que servir los assets estáticos.

options

Tipo: Object | undefined

Configura cómo se sirven los archivos; acepta las propiedades siguientes. Ver también el ejemplo más abajo.

dotfiles

Tipo: String Por defecto: "ignore"

Determina cómo se tratan los dotfiles (archivos o directorios que empiezan con un punto ”.”). Ver dotfiles más abajo.

etag

Tipo: Boolean Por defecto: true

Activa o desactiva la generación de etag.

Nota

express.static siempre envía ETags débiles.

extensions

Tipo: String[] | Boolean Por defecto: false

Establece fallbacks de extensiones de archivo: Si un archivo no se encuentra, busca archivos con las extensiones especificadas y sirve el primero que encuentre. Ejemplo: ['html', 'htm'].

fallthrough

Tipo: Boolean Por defecto: true

Permite que los errores del cliente pasen como peticiones no manejadas, de lo contrario reenvía un error del cliente. Ver fallthrough más abajo.

immutable

Tipo: Boolean Por defecto: false

Activa o desactiva la directiva immutable en el header de respuesta Cache-Control. Si está activado, la opción maxAge también debería especificarse para activar el caché. La directiva immutable evitará que los clientes soportados hagan peticiones condicionales durante la vida de la opción maxAge para comprobar si el archivo ha cambiado.

index

Tipo: String | Boolean Por defecto: "index.html"

Envía el archivo índice del directorio especificado. Establece a false para desactivar la indexación de directorios.

lastModified

Tipo: Boolean Por defecto: true

Establece el header Last-Modified a la fecha de última modificación del archivo en el SO.

maxAge

Tipo: Number Por defecto: 0

Establece la propiedad max-age del header Cache-Control en milisegundos o un string en formato ms.

redirect

Tipo: Boolean Por defecto: true

Redirige a la ”/” final cuando el pathname es un directorio.

setHeaders

Tipo: Function

Función para establecer headers HTTP para servir con el archivo. Ver setHeaders más abajo.

acceptRanges

Tipo: Boolean Por defecto: true

Activa o desactiva la aceptación de peticiones con rangos. Desactivar esto no enviará el header Accept-Ranges e ignorará el contenido del header Range de la petición.

cacheControl

Tipo: Boolean Por defecto: true

Activa o desactiva el establecimiento del header de respuesta Cache-Control. Desactivar esto ignorará las opciones immutable y maxAge.

Esta es una función middleware integrada en Express. Sirve archivos estáticos y está basada en serve-static.

Nota

Para mejores resultados, usa un cache de reverse proxy para mejorar el rendimiento al servir assets estáticos.

El argumento root especifica el directorio raíz desde donde se sirven los recursos estáticos. La función determina el archivo a servir combinando req.url con el directorio root proporcionado. Cuando no se encuentra un archivo, en lugar de enviar una respuesta 404, llama a next() para pasar al siguiente middleware, permitiendo apilamiento y respaldos.

Para más información, ver Sirviendo archivos estáticos en Express. y Usando middleware - Middleware integrado.

dotfiles

Los valores posibles para esta opción son:

"allow" - Sin tratamiento especial para dotfiles.
“deny” - Deniega una petición de un dotfile, responde con 403, luego llama a next().
“ignore” - Actúa como si el dotfile no existiera, responde con 404, luego llama a next().

fallthrough

Cuando esta opción es true, los errores del cliente como una petición incorrecta o una petición a un archivo inexistente harán que este middleware simplemente llame a next() para invocar el siguiente middleware en la pila. Cuando es false, estos errores (incluso 404s), invocarán next(err).

Establece esta opción a true para poder mapear múltiples directorios físicos a la misma dirección web o para que las rutas llenen archivos inexistentes.

Usa false si has montado este middleware en una ruta diseñada para ser estrictamente un único directorio del sistema de archivos, lo que permite short-circuit 404s con menos overhead. Este middleware también responderá a todos los métodos.

setHeaders

Para esta opción, especifica una función para establecer headers de respuesta personalizados. Las alteraciones a los headers deben ocurrir sincrónicamente.

La firma de la función es:

fn(res, path, stat);

Argumentos:

res, el objeto response.
path, la ruta del archivo que se está enviando.
stat, el objeto stat del archivo que se está enviando.

Ejemplo de express.static

Aquí hay un ejemplo de uso de la función middleware express.static con un objeto de opciones elaborado:

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

const options = {
  dotfiles: 'ignore',
  etag: false,
  extensions: ['htm', 'html'],
  index: false,
  maxAge: '1d',
  redirect: false,
  setHeaders(res, path, stat) {
    res.set('x-timestamp', Date.now());
  },
};

app.use(express.static('public', options));

import express from 'express';

const app = express();

const options = {
  dotfiles: 'ignore',
  etag: false,
  extensions: ['htm', 'html'],
  index: false,
  maxAge: '1d',
  redirect: false,
  setHeaders(res, path, stat) {
    res.set('x-timestamp', Date.now());
  },
};

app.use(express.static('public', options));

express.text()

Argumentos

options

Tipo: Object | undefined

Configura cómo se parsea el body de texto; acepta las propiedades siguientes.

defaultCharset

Tipo: String Por defecto: "utf-8"

Especifica el set de caracteres por defecto para el contenido de texto si el charset no se especifica en el header Content-Type de la petición.

inflate

Tipo: Boolean Por defecto: true

Activa o desactiva el manejo de bodies deflados (comprimidos); cuando está desactivado, los bodies deflados son rechazados.

limit

Tipo: Number | String Por defecto: "100kb"

Controla el tamaño máximo del body de la petición. Si es un número, entonces el valor especifica el número de bytes; si es un string, el valor se pasa a la librería bytes para su parseo.

type

Tipo: String | String[] | Function Por defecto: "text/plain"

Esto se usa para determinar qué tipo de media parseará el middleware. Esta opción puede ser un string, un array de strings, o una función. Si no es una función, la opción type se pasa directamente a la librería type-is y esto puede ser un nombre de extensión (como txt), un tipo mime (como text/plain), o un tipo mime con un comodín (como */* o text/*). Si es una función, la opción type se llama como fn(req) y la petición se parsea si devuelve un valor truthy.

verify

Tipo: Function Por defecto: undefined

Esta es una función middleware integrada en Express. Parsea los payloads de las peticiones entrantes en un string y está basada en body-parser.

Devuelve middleware que parsea todos los bodies como un string y solo mira las peticiones donde el header Content-Type coincide con la opción type. Este parser acepta cualquier codificación Unicode del body y soporta la inflación automática de las codificaciones gzip y deflate.

Un nuevo string body que contiene los datos analizados se popula en el objeto request después del middleware (es decir, req.body), o undefined si no había body que analizar, el Content-Type no coincidió, o ocurrió un error.

Advertencia

Como la forma de req.body está basada en entrada controlada por el usuario, todas las propiedades y valores en este objeto son no confiables y deberían validarse antes de confiar en ellos. Por ejemplo, req.body.trim() puede fallar de múltiples maneras, por ejemplo al apilar múltiples parsers req.body puede ser de un parser diferente. Se recomienda comprobar que req.body es un string antes de llamar métodos de string.

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

// parse requests with a Content-Type of text/plain into a string
app.use(express.text());

app.post('/', (req, res) => {
  console.dir(typeof req.body); // => 'string'
  res.send(req.body);
});

import express from 'express';

const app = express();

// parse requests with a Content-Type of text/plain into a string
app.use(express.text());

app.post('/', (req, res) => {
  console.dir(typeof req.body); // => 'string'
  res.send(req.body);
});

express.urlencoded()

Argumentos

options

Tipo: Object | undefined

Configura cómo se parsea el body URL-encoded; acepta las propiedades siguientes.

extended

Tipo: Boolean Por defecto: false

Esta opción permite elegir entre parsear los datos URL-encoded con la librería querystring (cuando es false) o la librería qs (cuando es true). La sintaxis "extended" permite que objetos ricos y arrays se codifiquen en el formato URL-encoded, permitiendo una experiencia similar a JSON con URL-encoded. Para más información, ver la librería qs.

inflate

Tipo: Boolean Por defecto: true

Activa o desactiva el manejo de bodies deflados (comprimidos); cuando está desactivado, los bodies deflados son rechazados.

limit

Tipo: Number | String Por defecto: "100kb"

Controla el tamaño máximo del body de la petición. Si es un número, entonces el valor especifica el número de bytes; si es un string, el valor se pasa a la librería bytes para su parseo.

parameterLimit

Tipo: Number Por defecto: 1000

Esta opción controla el número máximo de parámetros permitidos en los datos URL-encoded. Si una petición contiene más parámetros que este valor, se lanzará un error.

type

Tipo: String | String[] | Function Por defecto: "application/x-www-form-urlencoded"

Esto se usa para determinar qué tipo de media parseará el middleware. Esta opción puede ser un string, un array de strings, o una función. Si no es una función, la opción type se pasa directamente a la librería type-is y esto puede ser un nombre de extensión (como urlencoded), un tipo mime (como application/x-www-form-urlencoded), o un tipo mime con un comodín (como */x-www-form-urlencoded). Si es una función, la opción type se llama como fn(req) y la petición se parsea si devuelve un valor truthy.

verify

Tipo: Function Por defecto: undefined

defaultCharset

Tipo: String Por defecto: "utf-8"

El charset predeterminado para analizar, si no se especifica en el content-type. Debe ser utf-8 o iso-8859-1.

charsetSentinel

Tipo: Boolean Por defecto: false

Si se permite que el valor del parámetro utf8 tome precedencia como selector de charset. Requiere que el formulario contenga un parámetro llamado utf8 con un valor de ✓.

interpretNumericEntities

Tipo: Boolean Por defecto: false

Si se decodifican entidades numéricas como ☺ al analizar un formulario iso-8859-1.

depth

Tipo: Number Por defecto: 32

Configura la profundidad máxima de la librería qs cuando extended es true. Esto te permite limitar la cantidad de claves que se parsean y puede ser útil para prevenir ciertos tipos de abuso. Se recomienda mantener este valor lo más bajo posible.

Esta es una función middleware integrada en Express. Parsea las peticiones entrantes con payloads urlencoded y está basada en body-parser.

Devuelve middleware que solo parsea bodies urlencoded y solo mira las peticiones donde el header Content-Type coincide con la opción type. Este parser acepta solo codificación UTF-8 del body y soporta la inflación automática de las codificaciones gzip y deflate.

Un nuevo objeto body que contiene los datos analizados se popula en el objeto request después del middleware (es decir, req.body), o undefined si no había body que analizar, el Content-Type no coincidió, o ocurrió un error. Este objeto contendrá pares clave-valor, donde el valor puede ser un string o un array (cuando extended es false), o cualquier tipo (cuando extended es true).

Advertencia

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

// parse requests with a Content-Type of application/x-www-form-urlencoded
app.use(express.urlencoded({ extended: true }));

app.post('/profile', (req, res) => {
  console.dir(req.body);
  res.json(req.body);
});

import express from 'express';

const app = express();

// parse requests with a Content-Type of application/x-www-form-urlencoded
app.use(express.urlencoded({ extended: true }));

app.post('/profile', (req, res) => {
  console.dir(req.body);
  res.json(req.body);
});