Registry / web-framework / koa-route

koa-route

JSON →
library4.0.1jsnpmunverified

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.

web-framework
npm install koa-route
github ↗package ↗
INSTALL
IMPORT
SIG · KOA-ROUTE
K
koa-route
web-frameworkjavascriptv4.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Default export object
✓ import route from 'koa-route';
✗ import { get } from 'koa-route';
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.
CommonJS require
✓ const _ = require('koa-route');
✗ const { get } = require('koa-route');
This is the historical and most common import pattern shown in `koa-route`'s documentation for CommonJS environments.
Middleware and Context Types
✓ import type { Middleware, Context } from 'koa'; import route from 'koa-route';
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`.

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.

const _ = require('koa-route'); const Koa = require('koa'); const app = new Koa(); const db = { tobi: { name: 'tobi', species: 'ferret' }, loki: { name: 'loki', species: 'ferret' }, jane: { name: 'jane', species: 'ferret' } }; const pets = { list: (ctx) => { const names = Object.keys(db); ctx.body = 'pets: ' + names.join(', '); }, show: (ctx, name) => { const pet = db[name]; if (!pet) return ctx.throw('cannot find that pet', 404); ctx.body = pet.name + ' is a ' + pet.species; } }; app.use(_.get('/pets', pets.list)); app.use(_.get('/pets/:name', pets.show)); const PORT = process.env.PORT || 3000; app.listen(PORT, (err) => { if (err) console.error(err.stack); else console.log(`Koa server listening on port ${PORT}`); });
Debug
Known issues
breakingUpgrading 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.
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.
affects: >=4.0.0
breaking`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.
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"`).
affects: >=3.0.0
gotchaIn `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.
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.
affects: 4.0.0
gotchaMany `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.
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.
affects: *
Errors
Common errors & fixes
Cannot GET /some-undefined-route
The requested URL path and HTTP method do not match any defined route using `koa-route` in your application.
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.
TypeError: handler must be a function
`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.
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.
ReferenceError: _ is not defined
The `koa-route` module was not correctly imported or assigned to the `_` variable before being used in the application.
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.
Upgrade
Version history
4.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/koajs/route ↗
packagehttps://www.npmjs.com/package/koa-route ↗
koa-route — npm install koa-route · libregistry