Express.js
Explica cómo actualizar proyectos a Express 5 mediante inventario, tests, codemods, revisión de rutas, async handlers, middleware y rollout controlado.
Migrar una major version no consiste en cambiar un número y reparar el primer error. Debes revisar runtime, routing, middleware, contratos, tipos, tests y operación como un cambio coordinado.
Express 5 es la referencia moderna del notebook. A julio de 2026, npm publica Express 5.2.1 como etiqueta latest; Express 4.22.2 continúa como latest-4. Las ramas 5.x y 4.x siguen soportadas oficialmente, aunque solo la versión más reciente de cada major recibe soporte. Express 5 requiere Node.js 18 o superior.
Referencias:
Una aplicación Express depende de más que el paquete principal:
Node.js
+ Express
+ path matching
+ middleware externo
+ @types/express
+ tests
+ proxy/deploymentUn cambio puede compilar y aun romper rutas, errores, MIME types o seguridad en producción. La migración necesita inventario y evidencia.
Antes de actualizar:
Migrar desde una versión 4 antigua directamente aumenta variables.
La guía oficial ofrece una receta:
npx codemod@latest @expressjs/v5-migration-recipeLos codemods corrigen patrones mecánicos, no comprenden el negocio. Revisa el diff, ejecuta formatter, typecheck y tests. No reemplazan la migration guide.
En Express 5, un handler o middleware que retorna una Promise propaga su rechazo a next(error):
app.get('/orders/:id', async (request, response) => {
const order = await orders.findById(request.params.id);
response.json(order);
});Esto permite retirar wrappers como asyncHandler si ya no aportan otra función. Pero solo aplica al trabajo que forma parte de la Promise retornada.
app.post('/jobs', async (_request, response) => {
startDetachedWork(); // Sigue fuera del lifecycle
response.sendStatus(202);
});Revisa wrappers existentes para evitar doble next(error) o comportamiento duplicado.
Express 5 actualiza path-to-regexp. Las rutas string necesitan revisión.
// Express 4 habitual
app.get('/*', handler);
// Express 5
app.get('/*splat', handler);Para incluir la raíz, la guía utiliza braces:
app.get('/{*splat}', handler);La sintaxis ? se reemplaza por braces:
// Antes
'/:file.:ext?'
// Ahora
'/:file{.:ext}'Patrones que utilizaban caracteres especiales o expresiones dentro del string deben reescribirse como rutas explícitas o arrays.
No migres rutas solo por inspección; prueba una tabla de paths válidos e inválidos.
La guía oficial enumera signatures heredadas retiradas. Ejemplos a revisar:
res.send(status).res.sendfile() en favor de res.sendFile().res.send, res.json y res.redirect con status.app.del() en favor de app.delete().app.router heredado.req.param().Ejemplo:
// Ambiguo/retirado
res.send(201);
// Explícito
res.sendStatus(201);
// o
res.status(201).send(body);Busca usos con codemod, grep y typecheck.
Sin un parser compatible, req.body queda undefined en Express 5, en lugar de un objeto vacío en ciertos comportamientos anteriores.
Esto es más honesto, pero rompe código que asume {}:
if (Object.keys(request.body).length === 0) { ... }Registra parsers antes de las rutas y valida unknown.
req.query pasa a ser un getter y el parser predeterminado es el modo simple. Aplicaciones que dependían de objetos anidados o mutaban req.query necesitan corregirse.
No dependas de parsing complejo implícito. Define una convención y valida la forma resultante.
Express 5 conserva el puerto en req.host. Código que esperaba solo hostname debe utilizar la propiedad adecuada o normalizar explícitamente.
Para URLs públicas sensibles, utiliza configuración en lugar de Host no confiable.
El status debe ser un entero entre 100 y 999; valores inválidos lanzan error. Esto revela bugs antes ocultos.
Valida cualquier mapping dinámico y no uses status del cliente directamente.
Express 5 ignora maxAge y expires enviados a clearCookie; la limpieza debe usar las mismas opciones de alcance —path, domain, sameSite, secure— con las que se creó la cookie.
Prueba logout en el navegador/topología real.
En Express 5, el callback recibe errores de escucha en vez de que algunos errores se lancen fuera del callback:
const server = app.listen(port, (error) => {
if (error) {
logger.error({ error }, 'Listen failed');
return;
}
logger.info('Server started');
});También puedes usar createServer(app) y escuchar el evento error directamente.
Express 5 utiliza el paquete mime-types en APIs como res.sendFile y express.static, por lo que algunos Content-Type pueden cambiar respecto a Express 4.
Prueba downloads, assets, cache keys y consumidores que comparan headers exactamente.
Revisa:
headersSent.next(error).Una migración es una oportunidad para separar errores esperados de fallos de programación, pero no cambies todo el contrato a la vez sin necesidad.
Para cada paquete confirma:
Prueba especialmente sessions, uploads, auth, rate limiting, compression, OpenAPI y testing.
Alinea:
express 5.x
@types/express 5.x
Node types compatibles
TypeScript/config ESMLos tipos pueden revelar signatures retiradas, pero no detectan cambios de route matching ni runtime parsing.
DomiSys tiene fallback SPA app.get('*', ...), rutas opcionales y un wrapper async.
Migración:
/{*splat}./, /api, assets y rutas desconocidas.Conserva:
Si migración incluye cambio destructivo de DB o auth, el rollback deja de ser simple. Separa esos cambios.
Compara antes/después:
Un aumento de 404 puede indicar matching roto, no tráfico inválido.
No detecta cambios de runtime.
Puede propagar dos veces o esconder stacks.
Dificulta atribuir fallos. A veces es necesario, pero entonces aumenta testing/canary.
Es uno de los cambios más relevantes.
No entiende contrato ni middleware.
Crea una falsa sensación de compatibilidad.
Express 4 sigue soportado oficialmente. Puede ser razonable si una dependencia crítica no es compatible y existe un plan de migración con owner y fecha.
No uses esto para posponer indefinidamente updates de seguridad. Mantén la última 4.x y monitorea soporte.
/* necesita cambiar?req.body puede romper código previo?Antipatrones de Express con contexto convierte los errores recurrentes del notebook en decisiones prácticas, no prohibiciones absolutas.