Express URL Rewrite Middleware

Common errors

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

  cause Attempting to use `express-urlrewrite` without correctly importing or calling the `rewrite` function, or passing an invalid argument to `app.use()`.
  fix Ensure `express-urlrewrite` is correctly imported and `rewrite` is called with its arguments: `app.use(rewrite('/pattern', '/replacement'))`. For ESM, use `import rewrite from 'express-urlrewrite';`.

• My URL rewrite is not working, the browser still has the same link / Express redirect wrong url

  cause This middleware performs an *internal* rewrite of `req.url`, not an HTTP redirect. The browser's address bar will not change.
  fix This is the intended behavior of `express-urlrewrite`. If you require a browser-visible redirect (changing the URL in the address bar), use Express's `res.redirect()` method instead. For example: `app.get('/old-path', (req, res) => res.redirect('/new-path'));`.

• Regular expression for rewrite does not match expected URLs.

  cause Special characters in the URL path, such as `.` (dot) or `?` (question mark), are not properly escaped in the regular expression pattern passed to `rewrite`.
  fix Escape regex special characters. For example, to match a literal question mark in the URL's path, use `\\?`. To match a literal dot, use `\\.` in your pattern. Test your regex thoroughly.

Warnings

• gotcha When using regular expressions for URL patterns, the query string delimiter `?` must be escaped with a double backslash (`\\?`) if you intend to match it literally. Otherwise, `?` acts as a quantifier in regex, which can lead to unexpected matching behavior.
  Fix: Ensure `?` is escaped to `\\?` in regex patterns if it's meant to match the literal character in the URL's query string.
• gotcha When `rewrite` is used as a route-specific middleware (e.g., `app.get('/route', rewrite(...))`), it passes control to the *next matching route* in the Express application, not merely the next middleware in the current stack. This differs from standard middleware behavior and is a powerful, but potentially confusing, feature introduced in v1.2.
  Fix: Understand that `app.get(path, rewrite(...), handler)` will effectively execute `rewrite(...)` and then try to match `handler` against the *rewritten* URL as a new route, rather than simply passing control down the current middleware chain. Design your route definitions accordingly.
• gotcha Prior to version 1.1, rewriting a URL to include a new query string (e.g., `/path` to `/anotherpath?param=some`) would not update `req.query`. This meant `req.query.param` would remain undefined.
  Fix: Upgrade to version 1.1.0 or newer to ensure `req.query` is automatically updated when the rewritten URL includes query parameters. If an upgrade is not possible, manually parse and assign query parameters to `req.query` in a subsequent middleware.

Install

• npm install express-urlrewrite npm
• yarn add express-urlrewrite yarn
• pnpm add express-urlrewrite pnpm

Imports

• rewrite
  wrong:

  const rewrite = require('express-urlrewrite');

  correct:

  import rewrite from 'express-urlrewrite';

  While the package ships TypeScript types, many older Express applications use CommonJS. For modern ESM projects, prefer the default import. CommonJS `require` is also fully supported.
• RewriteFunction

  import type { RequestHandler } from 'express';
  import type RewriteFunction from 'express-urlrewrite';

  For type-checking in TypeScript, `rewrite` is a RequestHandler. The main export itself is the function, so `typeof rewrite` can also be used as a type.
• Using with app.use

  app.use(rewrite('/oldpath', '/newpath'));

  The `rewrite` function is designed to be directly passed to `app.use()` or route-specific middleware functions like `app.get()`, `app.post()`, etc.

Quickstart

This quickstart sets up a basic Express server and demonstrates three common rewrite patterns: using route parameters, wildcards, and regex with query string handling. It shows how rewritten URLs are then handled by subsequent routes.

import express from 'express';
import rewrite from 'express-urlrewrite';

const app = express();
const PORT = process.env.PORT || 3000;

// Debugging can be enabled via environment variable: DEBUG=express-urlrewrite

// Rewrite /item/123 to /product/123
app.use(rewrite('/item/:id', '/product/:id'));

// Rewrite /legacy-js/vendor/jquery.js to /assets/js/vendor/jquery.js
// Uses wildcard to capture multiple segments
app.use(rewrite('/legacy-js/*', '/assets/js/$1'));

// Rewrite URLs with query string parameter directly into path segment
// Note: The '?' must be escaped in the regular expression
app.use(rewrite('/search\?q=:query', '/results/:query'));

app.get('/product/:id', (req, res) => {
  res.send(`Displaying product ID: ${req.params.id}`);
});

app.get('/assets/js/:path(*)', (req, res) => {
  res.send(`Serving static asset: ${req.params.path}`);
});

app.get('/results/:query', (req, res) => {
  res.send(`Search results for: ${req.params.query}`);
});

app.get('/', (req, res) => {
    res.send('Welcome! Try /item/456, /legacy-js/vendor/library.js, or /search?q=test');
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Try accessing:');
  console.log(`- http://localhost:${PORT}/item/456`);
  console.log(`- http://localhost:${PORT}/legacy-js/vendor/library.js`);
  console.log(`- http://localhost:${PORT}/search?q=example`);
});