{"id":17752,"library":"koa-path-match","title":"Koa Path Match","description":"koa-path-match is a lightweight routing middleware designed for Koa.js applications, currently stable at version 5.0.0. It functions as a minimalist path matcher built on top of the `path-match` library, which itself uses `path-to-regexp` for robust URL pattern matching, mirroring the routing logic found in Express.js. This package distinguishes itself by offering fine-grained control over HTTP method handling and advocating for a single-function-per-route paradigm, intentionally omitting the `next` parameter in method-specific middleware to streamline logic. Its release cycle is closely tied to major version updates of its core `path-to-regexp` dependency. It serves as an efficient solution for basic route dispatching without the complexity of a full-featured routing framework, suitable for microservices or simple API endpoints.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/path-match","tags":["javascript","koa","route","router"],"install":[{"cmd":"npm install koa-path-match","lang":"bash","label":"npm"},{"cmd":"yarn add koa-path-match","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-path-match","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for path pattern matching, tightly coupled to `koa-path-match`'s versioning.","package":"path-to-regexp","optional":false},{"reason":"Wrapper library that `koa-path-match` extends for its core functionality.","package":"path-match","optional":false}],"imports":[{"note":"The default export is a function that, when called, returns the router factory. It's often immediately invoked: `import routeFactory from 'koa-path-match'; const route = routeFactory();`","wrong":"import { route } from 'koa-path-match'","symbol":"route","correct":"import route from 'koa-path-match'"},{"note":"In CommonJS, `require` returns the factory function, which then needs to be invoked to get the router builder.","wrong":"const { route } = require('koa-path-match')","symbol":"route","correct":"const route = require('koa-path-match')()"},{"note":"Type import for configuration options passed to the route factory.","symbol":"PathMatchOptions","correct":"import type { PathMatchOptions } from 'koa-path-match'"}],"quickstart":{"code":"const Koa = require('koa');\nconst route = require('koa-path-match')(); // Initialize the router factory\nconst app = new Koa();\n\n// Simulate a database/data store\nconst Things = {\n  data: {\n    '123': { id: '123', name: 'Thing One' },\n    '456': { id: '456', name: 'Thing Two' }\n  },\n  async getById(id) {\n    return this.data[id];\n  },\n  async delete(id) {\n    delete this.data[id];\n  }\n};\n\napp.use(route('/:id(\\d+)')\n  .get(async ctx => {\n    const thing = await Things.getById(ctx.params.id);\n    if (thing) {\n      ctx.body = thing;\n    } else {\n      ctx.status = 404;\n      ctx.body = { message: 'Not Found' };\n    }\n  })\n  .delete(async ctx => {\n    await Things.delete(ctx.params.id);\n    ctx.status = 204;\n  })\n);\n\n// Generic 404 handler if no route matches\napp.use(async ctx => {\n  if (ctx.status === 404 && !ctx.body) {\n    ctx.body = { message: 'Route not handled' };\n  }\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Koa app running on port http://localhost:${PORT}`);\n  console.log('Try: GET http://localhost:3000/123');\n  console.log('Try: DELETE http://localhost:3000/456');\n});","lang":"javascript","description":"Demonstrates how to set up a basic Koa application using `koa-path-match` for method-specific routing and parameter extraction."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18 or higher, or pin `koa-path-match` to version 3.x for older Node.js environments.","message":"Version 4.0.0 and above of `koa-path-match` dropped support for Node.js versions prior to 18. Attempting to use it on older Node.js environments will result in runtime errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review the changelogs for `path-to-regexp` when upgrading major versions. Thoroughly test existing routes, particularly those with advanced regex patterns or custom options, after an upgrade.","message":"Major versions of `koa-path-match` (v3, v4, v5) update their underlying `path-to-regexp` dependency. These updates can introduce subtle breaking changes in how path patterns are parsed, especially for complex regular expressions or new features.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Be aware of potential key collisions in `ctx.params`. If you need to preserve existing keys, manually merge or rename them before `koa-path-match` sets its parameters, or use unique parameter names in your routes.","message":"When a route matches, any keys defined in the path (e.g., `:id`) will be set on `ctx.params`, potentially overwriting existing keys if they share the same name.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you require middleware chaining or explicit `next()` calls, define your middleware using the `app.use(route(path, fns...))` syntax with an array of middleware, or structure your application such that each route handler is self-contained.","message":"Middleware functions defined using method-specific chaining (e.g., `route().get(async ctx => { ... })`) are not passed the `next` function as a parameter. This is an intentional design choice to encourage single-function, single-responsibility handlers.","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":"If your project uses `type: \"module\"` in `package.json` or `.mjs` files, change `const route = require('koa-path-match')()` to `import routeFactory from 'koa-path-match'; const route = routeFactory();`","cause":"Attempting to use `require()` in an ECMAScript Module (ESM) context without proper configuration.","error":"ReferenceError: require is not defined"},{"fix":"Ensure you are calling the imported default export: `import routeFactory from 'koa-path-match'; const route = routeFactory();` instead of `import route from 'koa-path-match';`","cause":"Incorrectly importing the default export in ESM when the factory function itself needs to be called immediately.","error":"TypeError: (0 , koa_path_match_1.default) is not a function"},{"fix":"Update your Node.js environment to version 18 or newer (e.g., using `nvm install 18 && nvm use 18`) or downgrade `koa-path-match` to version 3.x if you cannot upgrade Node.js.","cause":"Running `koa-path-match` v4 or higher on an unsupported Node.js version.","error":"Error: 'koa-path-match' is not compatible with Node.js <18.0.0"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}