{"id":17432,"library":"express-urlrewrite","title":"Express URL Rewrite Middleware","description":"express-urlrewrite is an Express.js middleware designed for flexible URL rewriting within an application. It allows developers to transform incoming request URLs based on regular expressions, route parameters, or wildcard patterns, without performing HTTP redirects. This is crucial for internal routing, path normalization, or creating cleaner URLs. The library is currently at version 2.0.3 and appears to be in a maintenance phase, with the last publish over two years ago. Its key differentiators include robust support for dynamic rewriting using named or numeric route parameters, wildcards (`*`), and the ability to modify query strings. A notable feature is its capacity to act as route-specific middleware, passing control to the *next matching route* in the Express router rather than the general next middleware in the stack, offering fine-grained control over the request flow.","status":"maintenance","version":"2.0.3","language":"javascript","source_language":"en","source_url":"git://github.com/kapouer/express-urlrewrite","tags":["javascript","express","middleware","rewrite","redirect","url","typescript"],"install":[{"cmd":"npm install express-urlrewrite","lang":"bash","label":"npm"},{"cmd":"yarn add express-urlrewrite","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-urlrewrite","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is an Express.js middleware and requires Express to function.","package":"express","optional":false}],"imports":[{"note":"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.","wrong":"const rewrite = require('express-urlrewrite');","symbol":"rewrite","correct":"import rewrite from 'express-urlrewrite';"},{"note":"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.","symbol":"RewriteFunction","correct":"import type { RequestHandler } from 'express';\nimport type RewriteFunction from 'express-urlrewrite';"},{"note":"The `rewrite` function is designed to be directly passed to `app.use()` or route-specific middleware functions like `app.get()`, `app.post()`, etc.","symbol":"Using with app.use","correct":"app.use(rewrite('/oldpath', '/newpath'));"}],"quickstart":{"code":"import express from 'express';\nimport rewrite from 'express-urlrewrite';\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\n// Debugging can be enabled via environment variable: DEBUG=express-urlrewrite\n\n// Rewrite /item/123 to /product/123\napp.use(rewrite('/item/:id', '/product/:id'));\n\n// Rewrite /legacy-js/vendor/jquery.js to /assets/js/vendor/jquery.js\n// Uses wildcard to capture multiple segments\napp.use(rewrite('/legacy-js/*', '/assets/js/$1'));\n\n// Rewrite URLs with query string parameter directly into path segment\n// Note: The '?' must be escaped in the regular expression\napp.use(rewrite('/search\\?q=:query', '/results/:query'));\n\napp.get('/product/:id', (req, res) => {\n  res.send(`Displaying product ID: ${req.params.id}`);\n});\n\napp.get('/assets/js/:path(*)', (req, res) => {\n  res.send(`Serving static asset: ${req.params.path}`);\n});\n\napp.get('/results/:query', (req, res) => {\n  res.send(`Search results for: ${req.params.query}`);\n});\n\napp.get('/', (req, res) => {\n    res.send('Welcome! Try /item/456, /legacy-js/vendor/library.js, or /search?q=test');\n});\n\napp.listen(PORT, () => {\n  console.log(`Server running on http://localhost:${PORT}`);\n  console.log('Try accessing:');\n  console.log(`- http://localhost:${PORT}/item/456`);\n  console.log(`- http://localhost:${PORT}/legacy-js/vendor/library.js`);\n  console.log(`- http://localhost:${PORT}/search?q=example`);\n});\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure `?` is escaped to `\\\\?` in regex patterns if it's meant to match the literal character in the URL's query string.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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';`.","cause":"Attempting to use `express-urlrewrite` without correctly importing or calling the `rewrite` function, or passing an invalid argument to `app.use()`.","error":"TypeError: app.use() requires a middleware function but got a Object"},{"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'));`.","cause":"This middleware performs an *internal* rewrite of `req.url`, not an HTTP redirect. The browser's address bar will not change.","error":"My URL rewrite is not working, the browser still has the same link / Express redirect wrong url"},{"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.","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`.","error":"Regular expression for rewrite does not match expected URLs."}],"ecosystem":"npm","meta_description":null}