middleware serve-static

Instalar

Este es un módulo de Node.js disponible a través del registro npm. La instalación se hace usando el comando npm install:

npm install serve-static

API

const serveStatic = require('serve-static');

Crea una nueva función middleware para servir archivos desde un directorio root dado. El archivo a servir se determina combinando req.url con el directorio root proporcionado. Cuando no se encuentra un archivo, en lugar de enviar una respuesta 404, este módulo llamará a next() para pasar al siguiente middleware, permitiendo apilar y tener fallbacks.

Opciones

acceptRanges

Habilita o deshabilita la aceptación de peticiones con rangos, por defecto es true. Deshabilitar esto no enviará Accept-Ranges e ignorará el contenido de la cabecera de petición Range.

cacheControl

Habilita o deshabilita el establecimiento de la cabecera de respuesta Cache-Control, por defecto es true. Deshabilitar esto ignorará las opciones immutable y maxAge.

dotfiles

Establece cómo se tratan los “dotfiles” cuando se encuentran. Un dotfile es un archivo o directorio que comienza con un punto ("."). Ten en cuenta que esta comprobación se hace en la ruta misma sin verificar si la ruta realmente existe en el disco. Si se especifica root, solo se comprueban los dotfiles por encima del root (es decir, el propio root puede estar dentro de un dotfile cuando se establece a "deny").

'allow' Sin trato especial para los dotfiles.
'deny' Deniega una petición de un dotfile y 403/next().
'ignore' Finge que el dotfile no existe y 404/next().

El valor por defecto es 'ignore'.

etag

Habilita o deshabilita la generación de etag, por defecto es true.

extensions

Establece extensiones de archivo de respaldo. Cuando se establece, si no se encuentra un archivo, las extensiones dadas se añadirán al nombre del archivo y se buscará. La primera que exista será servida. Ejemplo: ['html', 'htm'].

El valor por defecto es false.

fallthrough

Establece el middleware para que los errores de cliente pasen al siguiente como simples peticiones no manejadas, en caso contrario reenvía el error de cliente. La diferencia es que los errores de cliente como una petición incorrecta o una petición a un archivo inexistente harán que este middleware simplemente haga next() a tu siguiente middleware cuando este valor es true. Cuando este valor es false, estos errores (incluso 404s), invocarán next(err).

Típicamente se desea true para que múltiples directorios físicos puedan ser mapeados a la misma dirección web o para que las rutas rellenen archivos inexistentes.

El valor false puede usarse si este middleware está montado en una ruta que está diseñada para ser estrictamente un único directorio del sistema de archivos, lo que permite hacer un cortocircuito de los 404s con menos sobrecarga. Este middleware también responderá a todos los métodos.

El valor por defecto es true.

immutable

Habilita o deshabilita la directiva immutable en la cabecera de respuesta Cache-Control, por defecto es false. Si se establece en true, la opción maxAge también debería especificarse para habilitar la caché. La directiva immutable evitará que los clientes compatibles hagan peticiones condicionales durante la vida de la opción maxAge para comprobar si el archivo ha cambiado.

index

Por defecto este módulo enviará archivos "index.html" en respuesta a una petición a un directorio. Para deshabilitar esto establece false o para proporcionar un nuevo index pasa una cadena o un array en el orden preferido.

lastModified

Habilita o deshabilita la cabecera Last-Modified, por defecto es true. Usa el valor de última modificación del sistema de archivos.

maxAge

Proporciona un max-age en milisegundos para caché http, por defecto es 0. Esto también puede ser una cadena aceptada por el módulo ms.

redirect

Redirige a la "/" final cuando el pathname es un directorio. Por defecto es true.

setHeaders

Función para establecer cabeceras personalizadas en la respuesta. Las alteraciones a las cabeceras deben ocurrir sincrónicamente. La función se llama como fn(res, path, stat), donde los argumentos son:

res el objeto de respuesta
path la ruta del archivo que se está enviando
stat el objeto stat del archivo que se está enviando

Ejemplos

Servir archivos con un servidor http vanilla de node.js

const finalhandler = require('finalhandler');
const http = require('http');
const serveStatic = require('serve-static');

// Serve up public/ftp folder
const serve = serveStatic('public/ftp', { index: ['index.html', 'index.htm'] });

// Create server
const server = http.createServer((req, res) => {
  serve(req, res, finalhandler(req, res));
});

// Listen
server.listen(3000);

Servir todos los archivos como descargas

const contentDisposition = require('content-disposition');
const finalhandler = require('finalhandler');
const http = require('http');
const serveStatic = require('serve-static');

// Serve up public/ftp folder
const serve = serveStatic('public/ftp', {
  index: false,
  setHeaders: setHeaders,
});

// Set header to force download
function setHeaders(res, path) {
  res.setHeader('Content-Disposition', contentDisposition(path));
}

// Create server
const server = http.createServer((req, res) => {
  serve(req, res, finalhandler(req, res));
});

// Listen
server.listen(3000);

Sirviendo usando express

Simple

Este es un ejemplo simple de uso de Express.

const express = require('express');
const serveStatic = require('serve-static');

const app = express();

app.use(serveStatic('public/ftp', { index: ['default.html', 'default.htm'] }));
app.listen(3000);

Múltiples roots

Este ejemplo muestra una forma simple de buscar a través de múltiples directorios. Los archivos se buscan primero en public-optimized/, luego en public/ como respaldo.

const express = require('express');
const path = require('path');
const serveStatic = require('serve-static');

const app = express();

app.use(serveStatic(path.join(__dirname, 'public-optimized')));
app.use(serveStatic(path.join(__dirname, 'public')));
app.listen(3000);

Diferentes configuraciones para rutas

Este ejemplo muestra cómo establecer un max age diferente dependiendo del archivo servido. En este ejemplo, los archivos HTML no se cachean, mientras que todo lo demás se cachea por 1 día.

const express = require('express');
const path = require('path');
const serveStatic = require('serve-static');

const app = express();

app.use(
  serveStatic(path.join(__dirname, 'public'), {
    maxAge: '1d',
    setHeaders: setCustomCacheControl,
  })
);

app.listen(3000);

function setCustomCacheControl(res, file) {
  if (path.extname(file) === '.html') {
    // Custom Cache-Control for HTML files
    res.setHeader('Cache-Control', 'public, max-age=0');
  }
}

Licencia

MIT