Express.js Web Framework

Common errors

• TypeError: app.use() requires a middleware function but got a Object

  cause Attempting to use an object, an incorrectly imported value, or a non-function as middleware in `app.use()` or `router.use()`.
  fix Ensure the argument passed to `app.use()` or `router.use()` is a valid function (e.g., `express.json()`, `myCustomMiddleware`) or an array of middleware functions.

• Cannot GET /some-undefined-route

  cause No route handler has been defined for the specific HTTP method (GET) and path (`/some-undefined-route`) that the client is requesting. This often results in a 404 Not Found response.
  fix Define a route handler using `app.get()`, `app.post()`, `app.put()`, etc., for the specific path and method. If serving static files, ensure `express.static()` middleware is correctly configured and placed before other routes.

• (node:12345) UnhandledPromiseRejectionWarning: Error: Something went wrong

  cause An asynchronous operation (typically a Promise) within a route or middleware rejected, and this rejection was not caught. The error was not passed to Express's error-handling middleware.
  fix For `async` middleware/routes, wrap the code in a `try...catch` block and call `next(error)` in the catch. Alternatively, use a dedicated library like `express-async-errors` to automatically catch promise rejections and pass them to your error handlers.

Warnings

• breaking Express v5.0.0 introduces significant breaking changes compared to v4.x, including dropped support for older Node.js versions, removal of some deprecated APIs, and simplifications to the codebase. Users migrating from Express 4.x should consult the official v5 release blog post and migration guide thoroughly before upgrading.
  Fix: Review the official Express v5 release blog post (expressjs.com/2024/10/15/v5-release.html) and migration guides to understand specific changes and ensure your Node.js environment meets the new requirements before upgrading.
• breaking Reverted breaking change in query parser: Versions `5.2.0` and `4.22.0` included an erroneous breaking change related to the extended query parser. This change, initially linked to `CVE-2024-51999` (later rejected), caused unexpected behavior for some applications. The change was fully reverted in the subsequent patch releases (`5.2.1` and `4.22.1`).
  Fix: Upgrade immediately to `5.2.1` or `4.22.1` (or newer) to avoid the unintended query parser behavior introduced in the prior patch. No security vulnerability was ultimately confirmed for this specific issue.
• security A security vulnerability, `CVE-2024-47764`, affecting the `cookie` dependency used by Express, relates to improper handling of cookie parsing. This could potentially lead to denial-of-service or other unexpected behaviors. Patches were released in Express `v5.0.1` and `v4.21.1`.
  Fix: Upgrade to Express `5.0.1` or `4.21.1` (or newer) to incorporate the security fix for `CVE-2024-47764` and ensure proper cookie handling.
• deprecated The magic string `"back"` used in `res.redirect('back')` is deprecated since `v4.21.0` (and consequently in v5.x). While still functional for backward compatibility, its use is discouraged in favor of explicit URLs or more robust redirect handling mechanisms.
  Fix: Replace `res.redirect('back')` with a specific URL or implement custom logic to determine the previous URL from request headers (e.g., `req.get('Referrer')`) for explicit and predictable redirects.
• gotcha Middleware order is critical in Express. Middleware functions are executed in the sequence they are defined. If a middleware like `express.json()` or `express.static()` is placed after a route handler that it's meant to affect, it will not be executed for that request, leading to unexpected behavior (e.g., `req.body` being undefined).
  Fix: Always define global or route-specific middleware functions before the route handlers they are intended to process. Ensure error-handling middleware is defined last in the middleware chain.
• gotcha Asynchronous errors (unhandled promise rejections) in middleware or route handlers are not caught by default by Express's built-in error handling mechanism. If an `async` function throws an error without explicitly calling `next(err)`, the Node.js process may crash with an `UnhandledPromiseRejectionWarning`.
  Fix: Wrap `async` route handlers and middleware in a `try...catch` block and call `next(error)` in the catch block to pass errors to the Express error handler. Alternatively, use a package like `express-async-errors` to automatically wrap and handle promise rejections.

Install

• npm install alemmi npm
• yarn add alemmi yarn
• pnpm add alemmi pnpm

Imports

• express
  wrong:

  import { express } from 'express';

  correct:

  import express from 'express';

  The `express` module exports its primary application factory as a default export, which is the function used to create an application instance. Named imports for the `express` function itself are incorrect.
• Request, Response, NextFunction
  wrong:

  import { Request, Response, NextFunction } from 'express';

  correct:

  import type { Request, Response, NextFunction } from 'express';

  For TypeScript projects, these types are essential for correctly typing middleware and route handler parameters. Using `import type` is the recommended practice for importing only type definitions to prevent potential bundling issues or runtime errors in environments that don't fully support type-only imports as values.
• express.json(), express.static()
  wrong:

  import { json } from 'express';

  correct:

  import express from 'express'; const app = express(); app.use(express.json());

  Built-in middleware functions like `json()` (for parsing JSON request bodies) and `static()` (for serving static files) are properties of the default `express` export. They should be accessed via the imported `express` object, not as top-level named imports.

Quickstart

This quickstart demonstrates a basic Express.js server using TypeScript and ES modules. It includes JSON body parsing middleware, a custom logging middleware, a GET route, a POST route handling JSON data, and a fundamental error handler, showcasing a typical setup for an Express application.

import express, { Request, Response, NextFunction } from 'express';

const app = express();
const port = 3000;

// Middleware to parse JSON bodies
app.use(express.json());

// A simple logger middleware
app.use((req: Request, res: Response, next: NextFunction) => {
  console.log(`${req.method} ${req.url} at ${new Date().toISOString()}`);
  next();
});

// Define a GET route
app.get('/', (req: Request, res: Response) => {
  res.send('Hello from Express v5!');
});

// Define a POST route with a request body
app.post('/data', (req: Request, res: Response) => {
  if (req.body && typeof req.body === 'object' && 'message' in req.body) {
    res.json({ received: req.body.message, status: 'success' });
  } else {
    res.status(400).json({ error: 'Message not found in request body.' });
  }
});

// Error handling middleware (should be last)
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});

app.listen(port, () => {
  console.log(`Express server listening on http://localhost:${port}`);
});