{"id":17112,"library":"koa-route","title":"Koa Route Middleware","description":"koa-route provides a minimalist routing solution for Koa applications. It offers a simple API to define HTTP method-specific routes (e.g., `.get`, `.post`) directly as middleware functions. Its current stable version is 4.0.1. Releases are infrequent, primarily tied to underlying dependency updates or minor API refinements, reflecting its stable and mature nature. It differentiates itself from more feature-rich alternatives like `koa-router` by explicitly prioritizing simplicity and minimal overhead. This makes it suitable for smaller applications or specific middleware-based routing needs where the full complexity of a dedicated routing framework is not required, as it does not offer advanced features such as nested routes, prefixing, or extensive middleware composition.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/route","tags":["javascript","koa","middleware","routes","router","route"],"install":[{"cmd":"npm install koa-route","lang":"bash","label":"npm"},{"cmd":"yarn add koa-route","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-route","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports an object containing HTTP method helpers as properties. While the documentation often uses `_`, aliasing it to `route` is a common and clearer practice for ESM.","wrong":"import { get } from 'koa-route';","symbol":"Default export object","correct":"import route from 'koa-route';"},{"note":"This is the historical and most common import pattern shown in `koa-route`'s documentation for CommonJS environments.","wrong":"const { get } = require('koa-route');","symbol":"CommonJS require","correct":"const _ = require('koa-route');"},{"note":"For TypeScript projects, types for Koa's `Middleware` and `Context` should be imported from 'koa'. While `koa-route` itself is JavaScript, its handlers conform to Koa's middleware signature, and its types are available via `@types/koa-route`.","symbol":"Middleware and Context Types","correct":"import type { Middleware, Context } from 'koa';\nimport route from 'koa-route';"}],"quickstart":{"code":"const _ = require('koa-route');\nconst Koa = require('koa');\nconst app = new Koa();\n\nconst db = {\n  tobi: { name: 'tobi', species: 'ferret' },\n  loki: { name: 'loki', species: 'ferret' },\n  jane: { name: 'jane', species: 'ferret' }\n};\n\nconst pets = {\n  list: (ctx) => {\n    const names = Object.keys(db);\n    ctx.body = 'pets: ' + names.join(', ');\n  },\n\n  show: (ctx, name) => {\n    const pet = db[name];\n    if (!pet) return ctx.throw('cannot find that pet', 404);\n    ctx.body = pet.name + ' is a ' + pet.species;\n  }\n};\n\napp.use(_.get('/pets', pets.list));\napp.use(_.get('/pets/:name', pets.show));\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, (err) => {\n  if (err) console.error(err.stack);\n  else console.log(`Koa server listening on port ${PORT}`);\n});","lang":"javascript","description":"This quickstart demonstrates how to set up basic GET routes for a simple pet API using `koa-route` with a Koa application, handling both listing all pets and showing a specific pet by name."},"warnings":[{"fix":"Review `path-to-regexp` v6 documentation for changes. Thoroughly test existing routes after upgrading and adjust path definitions if necessary to match the new parsing behavior.","message":"Upgrading to `koa-route` v4.0.0 included an upgrade to `path-to-regexp@6`. This introduced subtle breaking changes in how routes are parsed, especially regarding advanced regex features, unnamed parameters, and trailing slashes, which may affect existing route definitions.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your Koa application is using Koa 2.x or later. For Koa 1.x projects, pin `koa-route` to a version less than `3.0.0` in your `package.json` (e.g., `\"koa-route\": \"^2.0.0\"`).","message":"`koa-route` v3.0.0 introduced support for Koa 2.x's async/await middleware signature, making it incompatible with Koa 1.x. Koa 1 applications using `koa-route` must remain on versions prior to 3.0.0.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade to `koa-route@4.0.1` or a later version to avoid this specific issue. If you must use v4.0.0, ensure all route handlers passed to `_.get()`, `_.post()`, etc., are explicitly functions.","message":"In `koa-route` v4.0.0 specifically, route handlers were strictly enforced to be functions, throwing a `TypeError` if a non-function was provided. This strict validation was immediately reverted in v4.0.1, making v4.0.0 an unstable release in this regard.","severity":"gotcha","affected_versions":"4.0.0"},{"fix":"Consider importing `koa-route` with a more descriptive and unique name like `route`, `koaRoute`, or `router` to avoid potential naming collisions and improve code clarity and maintainability.","message":"Many `koa-route` examples, including in its own documentation, suggest importing the module as `_`. While functional, this can lead to naming conflicts with other popular libraries that commonly use `_` (e.g., Lodash or Underscore.js), especially in larger codebases, potentially causing unexpected behavior or confusion.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify that the URL path (`/some-undefined-route`) and the HTTP method (GET) precisely match a route defined with `_.get('/some-undefined-route', handler)`. Check for typos in the path or an incorrect HTTP method.","cause":"The requested URL path and HTTP method do not match any defined route using `koa-route` in your application.","error":"Cannot GET /some-undefined-route"},{"fix":"Ensure the argument passed to `_.get()`, `_.post()`, etc., is indeed a function. This often happens due to typos in function names, unimported handlers, or incorrect variable assignments.","cause":"`koa-route` expects a valid Koa middleware function as the second argument to its method helpers (e.g., `_.get()`, `_.post()`). This error occurs if a non-function value is passed.","error":"TypeError: handler must be a function"},{"fix":"For CommonJS, add `const _ = require('koa-route');` at the top of your file. For ESM, use `import _ from 'koa-route';` or `import route from 'koa-route';` to import the module.","cause":"The `koa-route` module was not correctly imported or assigned to the `_` variable before being used in the application.","error":"ReferenceError: _ is not defined"}],"ecosystem":"npm","meta_description":null}