{"id":17762,"library":"koa-rewrite-75lb","title":"Koa URL Rewrite Middleware","description":"koa-rewrite is a specialized URL rewriting middleware designed for the Koa.js web framework. It enables developers to dynamically modify incoming request URLs based on defined patterns before they are processed by subsequent middleware or routing logic. The current stable version, 3.0.1, is compatible with Koa v2 and newer, while `koa-rewrite@1` is designated for Koa v1 applications. The library offers flexible rewrite rule definition through regular expressions, named and numeric route parameters, and wildcard matching. It provides a focused, lightweight solution for common URL manipulation needs within the Koa ecosystem, prioritizing simplicity and efficiency for path transformations rather than comprehensive routing. Releases are infrequent, primarily aligning with significant Koa framework updates.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/rewrite","tags":["javascript","koa","middleware","rewrite","redirect","url"],"install":[{"cmd":"npm install koa-rewrite-75lb","lang":"bash","label":"npm"},{"cmd":"yarn add koa-rewrite-75lb","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-rewrite-75lb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `rewrite` middleware function is exported as the default export for ESM modules.","wrong":"import { rewrite } from 'koa-rewrite';\nimport * as rewrite from 'koa-rewrite';","symbol":"rewrite","correct":"import rewrite from 'koa-rewrite';"},{"note":"For CommonJS environments, the entire module export is the `rewrite` function.","wrong":"const { rewrite } = require('koa-rewrite');\nconst rewrite = require('koa-rewrite').default;","symbol":"rewrite","correct":"const rewrite = require('koa-rewrite');"}],"quickstart":{"code":"import Koa from 'koa';\nimport rewrite from 'koa-rewrite';\nimport Router from '@koa/router';\n\nconst app = new Koa();\nconst router = new Router();\n\n// Middleware order matters: rewrite before router\napp.use(rewrite(/^\\/i(\\d+)/, '/items/$1'));\napp.use(rewrite('/:src..:dst', '/commits/:src/to/:dst'));\napp.use(rewrite('/js/(.*)', '/public/assets/js/$1')); // Example: /js/main.js -> /public/assets/js/main.js\n\nrouter.get('/items/:id', (ctx) => {\n  ctx.body = `Item ID: ${ctx.params.id}`;\n});\n\nrouter.get('/commits/:src/to/:dst', (ctx) => {\n  ctx.body = `Commits from ${ctx.params.src} to ${ctx.params.dst}`;\n});\n\nrouter.get('/public/assets/js/:path*', (ctx) => {\n  ctx.body = `Serving static JS file: /public/assets/js/${ctx.params.path}`;\n});\n\nrouter.get('/', (ctx) => {\n  ctx.body = 'Hello, Koa Rewrite!';\n});\n\napp.use(router.routes()).use(router.allowedMethods());\n\nconst PORT = process.env.PORT ?? 3000;\napp.listen(PORT, () => {\n  console.log(`Koa server running on http://localhost:${PORT}`);\n  console.log('Try:');\n  console.log(`- http://localhost:${PORT}/i123 (should rewrite to /items/123)`);\n  console.log(`- http://localhost:${PORT}/foo..bar (should rewrite to /commits/foo/to/bar)`);\n  console.log(`- http://localhost:${PORT}/js/vendor/library.js (should rewrite to /public/assets/js/vendor/library.js)`);\n});","lang":"javascript","description":"This example sets up a basic Koa application with `koa-rewrite` to demonstrate regex, parameter-based, and wildcard URL rewriting. It uses `@koa/router` to handle the rewritten paths. To run, install `koa`, `koa-rewrite`, and `@koa/router`."},"warnings":[{"fix":"Ensure your `koa-rewrite` version matches your Koa framework version. Upgrade Koa to v2+ or use `npm install koa-rewrite@1` if on Koa v1.","message":"Version `koa-rewrite@2.0.0` and above are exclusively compatible with Koa v2.x and newer. Applications using Koa v1.x must use `koa-rewrite@1.x`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Set the `DEBUG` environment variable (e.g., `DEBUG=koa-rewrite node app.js`) to see rewrite logs.","message":"Debugging output for `koa-rewrite` is controlled via the `DEBUG` environment variable. Enable it with `DEBUG=koa-rewrite`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Register `app.use(rewrite(...))` statements before `app.use(router.routes())` or static middleware.","message":"The order of middleware is crucial. `koa-rewrite` should be placed before any routing middleware (like `@koa/router`) or static file servers to ensure URL rewriting occurs before path matching.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Upgrade Koa to version 2 or higher (e.g., `npm install koa@latest`) or downgrade `koa-rewrite` to version 1 (e.g., `npm install koa-rewrite@1`).","cause":"Attempting to use `koa-rewrite@2+` with an application initialized with Koa v1, which has different API patterns for `app.use`.","error":"TypeError: app.use is not a function"},{"fix":"Ensure `koa-rewrite` middleware is registered early in your application's middleware stack, typically before any routing middleware (`@koa/router`) or static file serving middleware.","cause":"The `koa-rewrite` middleware is placed too late in the Koa middleware chain, after a router or other middleware has already attempted to match the original URL and failed, or the original URL was consumed.","error":"404 Not Found (when a rewrite rule should apply)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}