@koa/router
Advanced tools
Modern TypeScript Router middleware for Koa. Maintained by Forward Email and Lad.
app.get, app.post, app.put, etc.npm:
npm install @koa/router
yarn:
yarn add @koa/router
Requirements:
@koa/router is written in TypeScript and includes comprehensive type definitions out of the box. No need for @types/* packages!
Types are automatically inferred - no explicit type annotations needed:
import Router from '@koa/router';
const router = new Router();
// ctx and next are automatically inferred!
router.get('/:id', (ctx, next) => {
const id = ctx.params.id; // ✅ Inferred as string
ctx.request.params.id; // ✅ Also available
ctx.body = { id }; // ✅ Works
return next(); // ✅ Works
});
// Also works for router.use()
router.use((ctx, next) => {
ctx.state.startTime = Date.now();
return next();
});
For cases where you need explicit types:
import Router, { RouterContext } from '@koa/router';
import type { Next } from 'koa';
router.get('/:id', (ctx: RouterContext, next: Next) => {
const id = ctx.params.id;
ctx.body = { id };
});
The router supports generic type parameters for full type safety with custom state and context types:
import Router, { RouterContext } from '@koa/router';
import type { Next } from 'koa';
// Define your application state
interface AppState {
user?: {
id: string;
email: string;
};
}
// Define your custom context
interface AppContext {
requestId: string;
}
// Create router with generics
const router = new Router<AppState, AppContext>();
// Type-safe route handlers
router.get(
'/profile',
(ctx: RouterContext<AppState, AppContext>, next: Next) => {
// ctx.state.user is fully typed
if (ctx.state.user) {
ctx.body = {
user: ctx.state.user,
requestId: ctx.requestId // Custom context property
};
}
}
);
HTTP methods support generic type parameters to extend state and context types:
interface UserState {
user: { id: string; name: string };
}
interface UserContext {
permissions: string[];
}
// Extend types for specific routes
router.get<UserState, UserContext>(
'/users/:id',
async (ctx: RouterContext<UserState, UserContext>) => {
// ctx.state.user is fully typed
// ctx.permissions is fully typed
ctx.body = {
user: ctx.state.user,
permissions: ctx.permissions
};
}
);
import type { RouterParameterMiddleware } from '@koa/router';
import type { Next } from 'koa';
// Type-safe parameter middleware
router.param('id', ((value: string, ctx: RouterContext, next: Next) => {
if (!/^\d+$/.test(value)) {
ctx.throw(400, 'Invalid ID format');
}
return next();
}) as RouterParameterMiddleware);
import {
Router,
RouterContext,
RouterOptions,
RouterMiddleware,
RouterParameterMiddleware,
RouterParamContext,
AllowedMethodsOptions,
UrlOptions,
HttpMethod
} from '@koa/router';
import type { Next } from 'koa';
// Router with generics
type MyRouter = Router<AppState, AppContext>;
// Context with generics
type MyContext = RouterContext<AppState, AppContext, BodyType>;
// Middleware with generics
type MyMiddleware = RouterMiddleware<AppState, AppContext, BodyType>;
// Parameter middleware with generics
type MyParamMiddleware = RouterParameterMiddleware<
AppState,
AppContext,
BodyType
>;
ctx and next are inferred automatically in route handlersRouter<StateT, ContextT> for custom state and context typesctx.params is fully typed and always definedctx.state respects your state typeas const with methods option for typed custom methodsimport Koa from 'koa';
import Router from '@koa/router';
const app = new Koa();
const router = new Router();
// Define routes
router.get('/', (ctx, next) => {
ctx.body = 'Hello World!';
});
router.get('/users/:id', (ctx, next) => {
ctx.body = { id: ctx.params.id };
});
// Apply router middleware
app.use(router.routes()).use(router.allowedMethods());
app.listen(3000);
new Router([options])
Create a new router instance.
Options:
| Option | Type | Description |
|---|---|---|
prefix | string | Prefix all routes with this path |
exclusive | boolean | Only run the most specific matching route |
host | string | string[] | RegExp | Match routes only for this hostname(s) |
methods | string[] | Custom HTTP methods to support |
sensitive | boolean | Enable case-sensitive routing |
strict | boolean | Require trailing slashes |
Example:
const router = new Router({
prefix: '/api',
exclusive: true,
host: 'example.com'
});
Router provides methods for all standard HTTP verbs:
router.get(path, ...middleware)router.post(path, ...middleware)router.put(path, ...middleware)router.patch(path, ...middleware)router.delete(path, ...middleware) or router.del(path, ...middleware)router.head(path, ...middleware)router.options(path, ...middleware)router.connect(path, ...middleware) - CONNECT methodrouter.trace(path, ...middleware) - TRACE methodrouter.all(path, ...middleware) - Match any HTTP methodNote: All standard HTTP methods (as defined by Node.js http.METHODS) are automatically available as router methods. The methods option in the constructor can be used to limit which methods the router responds to, but you cannot use truly custom HTTP methods beyond the standard set.
Basic Example:
router
.get('/users', getUsers)
.post('/users', createUser)
.put('/users/:id', updateUser)
.delete('/users/:id', deleteUser)
.all('/users/:id', logAccess); // Runs for any method
Using Less Common HTTP Methods:
All standard HTTP methods from Node.js are automatically available. Here's an example using PATCH and PURGE:
const router = new Router();
// PATCH method (standard HTTP method for partial updates)
router.patch('/users/:id', async (ctx) => {
// Partial update
ctx.body = { message: 'User partially updated' };
});
// PURGE method (standard HTTP method, commonly used for cache invalidation)
router.purge('/cache/:key', async (ctx) => {
// Clear cache
await clearCache(ctx.params.key);
ctx.body = { message: 'Cache cleared' };
});
// COPY method (standard HTTP method)
router.copy('/files/:source', async (ctx) => {
await copyFile(ctx.params.source, ctx.request.body.destination);
ctx.body = { message: 'File copied' };
});
// Limiting which methods the router responds to
const apiRouter = new Router({
methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] // Only these methods
});
apiRouter.get('/users', getUsers);
apiRouter.post('/users', createUser);
// router.purge() won't work here because PURGE is not in the methods array
Note: HEAD requests are automatically supported for all GET routes. When you define a GET route, HEAD requests will execute the same handler and return the same headers but with an empty body.
Routes can be named for URL generation:
router.get('user', '/users/:id', (ctx) => {
ctx.body = { id: ctx.params.id };
});
// Generate URL
router.url('user', 3);
// => "/users/3"
router.url('user', { id: 3 });
// => "/users/3"
// With query parameters
router.url('user', { id: 3 }, { query: { limit: 10 } });
// => "/users/3?limit=10"
// In middleware
router.use((ctx, next) => {
ctx.redirect(ctx.router.url('user', 1));
});
Chain multiple middleware functions for a single route:
router.get(
'/users/:id',
async (ctx, next) => {
// Load user from database
ctx.state.user = await User.findById(ctx.params.id);
return next();
},
async (ctx, next) => {
// Check permissions
if (!ctx.state.user) {
ctx.throw(404, 'User not found');
}
return next();
},
(ctx) => {
// Send response
ctx.body = ctx.state.user;
}
);
Mount routers within routers:
const usersRouter = new Router();
usersRouter.get('/', getUsers);
usersRouter.get('/:id', getUser);
const postsRouter = new Router();
postsRouter.get('/', getPosts);
postsRouter.get('/:id', getPost);
const apiRouter = new Router({ prefix: '/api' });
apiRouter.use('/users', usersRouter.routes());
apiRouter.use('/posts', postsRouter.routes());
app.use(apiRouter.routes());
Note: Parameters from parent routes are properly propagated to nested router middleware and handlers.
Set a prefix for all routes in a router:
Option 1: In constructor
const router = new Router({ prefix: '/api' });
router.get('/users', handler); // Responds to /api/users
Option 2: Using .prefix()
const router = new Router();
router.prefix('/api');
router.get('/users', handler); // Responds to /api/users
With parameters:
const router = new Router({ prefix: '/api/v:version' });
router.get('/users', (ctx) => {
ctx.body = {
version: ctx.params.version,
users: []
};
});
// Responds to /api/v1/users, /api/v2/users, etc.
Note: Middleware now correctly executes when the prefix contains parameters.
Named parameters are captured and available at ctx.params:
router.get('/:category/:title', (ctx) => {
console.log(ctx.params);
// => { category: 'programming', title: 'how-to-node' }
ctx.body = {
category: ctx.params.category,
title: ctx.params.title
};
});
Optional parameters:
router.get('/user{/:id}?', (ctx) => {
// Matches both /user and /user/123
ctx.body = { id: ctx.params.id || 'all' };
});
Wildcard parameters:
router.get('/files/{/*path}', (ctx) => {
// Matches /files/a/b/c.txt
ctx.body = { path: ctx.params.path }; // => a/b/c.txt
});
Note: Custom regex patterns in parameters (:param(regex)) are no longer supported in v14+ due to path-to-regexp v8. Use validation in handlers or middleware instead.
Returns router middleware which dispatches matched routes.
app.use(router.routes());
Use middleware, if and only if, a route is matched.
Signature:
router.use([path], ...middleware);
Examples:
// Run for all matched routes
router.use(session());
// Run only for specific path
router.use('/admin', requireAuth());
// Run for multiple paths
router.use(['/admin', '/dashboard'], requireAuth());
// Run for RegExp paths
router.use(/^\/api\//, apiAuth());
// Mount nested routers
const nestedRouter = new Router();
router.use('/nested', nestedRouter.routes());
Note: Middleware path boundaries are correctly enforced. Middleware scoped to /api will only run for routes matching /api/*, not for unrelated routes.
Set the path prefix for a Router instance after initialization.
const router = new Router();
router.get('/', handler); // Responds to /
router.prefix('/api');
router.get('/', handler); // Now responds to /api
Returns middleware for responding to OPTIONS requests with allowed methods,
and 405 Method Not Allowed / 501 Not Implemented responses.
Options:
| Option | Type | Description |
|---|---|---|
throw | boolean | Throw errors instead of setting response |
notImplemented | function | Custom function for 501 errors |
methodNotAllowed | function | Custom function for 405 errors |
Example:
app.use(router.routes());
app.use(router.allowedMethods());
With custom error handling:
app.use(
router.allowedMethods({
throw: true,
notImplemented: () => new Error('Not Implemented'),
methodNotAllowed: () => new Error('Method Not Allowed')
})
);
Redirect source to destination URL with optional status code.
router.redirect('/login', 'sign-in', 301);
router.redirect('/old-path', '/new-path');
// Redirect to named route
router.get('home', '/', handler);
router.redirect('/index', 'home');
Lookup a route by name.
const layer = router.route('user');
if (layer) {
console.log(layer.path); // => /users/:id
}
Generate URL from route name and parameters.
router.get('user', '/users/:id', handler);
router.url('user', 3);
// => "/users/3"
router.url('user', { id: 3 });
// => "/users/3"
router.url('user', { id: 3 }, { query: { limit: 1 } });
// => "/users/3?limit=1"
router.url('user', { id: 3 }, { query: 'limit=1' });
// => "/users/3?limit=1"
In middleware:
router.use((ctx, next) => {
// Access router instance via ctx.router
const userUrl = ctx.router.url('user', ctx.state.userId);
ctx.redirect(userUrl);
return next();
});
Run middleware for named route parameters.
Signature:
router.param(param: string, middleware: RouterParameterMiddleware): Router
TypeScript Example:
import type { RouterParameterMiddleware } from '@koa/router';
import type { Next } from 'koa';
router.param('user', (async (id: string, ctx: RouterContext, next: Next) => {
ctx.state.user = await User.findById(id);
if (!ctx.state.user) {
ctx.throw(404, 'User not found');
}
return next();
}) as RouterParameterMiddleware);
router.get('/users/:user', (ctx: RouterContext) => {
// ctx.state.user is already loaded and typed
ctx.body = ctx.state.user;
});
router.get('/users/:user/friends', (ctx: RouterContext) => {
// ctx.state.user is available here too
return ctx.state.user.getFriends();
});
JavaScript Example:
router
.param('user', async (id, ctx, next) => {
ctx.state.user = await User.findById(id);
if (!ctx.state.user) {
ctx.throw(404, 'User not found');
}
return next();
})
.get('/users/:user', (ctx) => {
// ctx.state.user is already loaded
ctx.body = ctx.state.user;
})
.get('/users/:user/friends', (ctx) => {
// ctx.state.user is available here too
return ctx.state.user.getFriends();
});
Multiple param handlers:
You can register multiple param handlers for the same parameter. All handlers will be called in order, and each handler is executed exactly once per request (even if multiple routes match):
router
.param('id', validateIdFormat)
.param('id', checkIdExists)
.param('id', checkPermissions)
.get('/resource/:id', handler);
// All three param handlers run once per request
Generate URL from path pattern and parameters (static method).
const url = Router.url('/users/:id', { id: 1 });
// => "/users/1"
const url = Router.url('/users/:id', { id: 1, name: 'John' });
// => "/users/1"
Match routes only for specific hostnames:
// Exact match with single host
const routerA = new Router({
host: 'example.com'
});
// Match multiple hosts with array
const routerB = new Router({
host: ['some-domain.com', 'www.some-domain.com', 'some.other-domain.com']
});
// Match patterns with RegExp
const routerC = new Router({
host: /^(.*\.)?example\.com$/ // Match all subdomains
});
Host Matching Options:
string - Exact match (case-sensitive)string[] - Matches if the request host equals any string in the arrayRegExp - Pattern match using regular expressionundefined - Matches all hosts (default)Use RegExp for flexible path matching:
Full RegExp routes:
router.get(/^\/users\/(\d+)$/, (ctx) => {
const id = ctx.params[0]; // First capture group
ctx.body = { id };
});
RegExp in router.use():
router.use(/^\/api\//, apiMiddleware);
router.use(/^\/admin\//, adminAuth);
Validate parameters using middleware or handlers:
Option 1: In Handler
router.get('/user/:id', (ctx) => {
if (!/^\d+$/.test(ctx.params.id)) {
ctx.throw(400, 'Invalid ID format');
}
ctx.body = { id: parseInt(ctx.params.id, 10) };
});
Option 2: Middleware
function validateUUID(paramName) {
const uuidRegex =
/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
return async (ctx, next) => {
if (!uuidRegex.test(ctx.params[paramName])) {
ctx.throw(400, `Invalid ${paramName} format`);
}
await next();
};
}
router.get('/user/:id', validateUUID('id'), handler);
Option 3: router.param()
router.param('id', (value, ctx, next) => {
if (!/^\d+$/.test(value)) {
ctx.throw(400, 'Invalid ID');
}
ctx.params.id = parseInt(value, 10); // Convert to number
return next();
});
router.get('/user/:id', handler);
router.get('/post/:id', handler);
// Both routes validate :id parameter
Create a catch-all route that only runs when no other routes match:
router.get('/users', handler1);
router.get('/posts', handler2);
// Catch-all for unmatched routes
router.all('{/*rest}', (ctx) => {
if (!ctx.matched || ctx.matched.length === 0) {
ctx.status = 404;
ctx.body = { error: 'Not Found' };
}
});
Register multiple paths with the same middleware:
router.get(['/users', '/people'], handler);
// Responds to both /users and /people
Implement custom 404 handling:
app.use(router.routes());
// 404 middleware - runs after router
app.use((ctx) => {
if (!ctx.matched || ctx.matched.length === 0) {
ctx.status = 404;
ctx.body = {
error: 'Not Found',
path: ctx.path
};
}
});
// ✅ Good: Compose reusable middleware
const requireAuth = () => async (ctx, next) => {
if (!ctx.state.user) ctx.throw(401);
await next();
};
const requireAdmin = () => async (ctx, next) => {
if (!ctx.state.user.isAdmin) ctx.throw(403);
await next();
};
router.get('/admin', requireAuth(), requireAdmin(), adminHandler);
// ✅ Good: Group related routes
const usersRouter = new Router({ prefix: '/users' });
usersRouter.get('/', listUsers);
usersRouter.post('/', createUser);
usersRouter.get('/:id', getUser);
usersRouter.put('/:id', updateUser);
usersRouter.delete('/:id', deleteUser);
app.use(usersRouter.routes());
// ✅ Good: Name important routes
router.get('home', '/', homeHandler);
router.get('user-profile', '/users/:id', profileHandler);
// Easy to generate URLs
ctx.redirect(ctx.router.url('home'));
ctx.redirect(ctx.router.url('user-profile', ctx.state.user.id));
// ✅ Good: Validate at the route level
router
.param('id', validateId)
.get('/users/:id', getUser)
.put('/users/:id', updateUser)
.delete('/users/:id', deleteUser);
// Validation runs once for all routes
// ✅ Good: Centralized error handling
app.use(async (ctx, next) => {
try {
await next();
} catch (err) {
ctx.status = err.status || 500;
ctx.body = {
error: err.message,
...(process.env.NODE_ENV === 'development' && { stack: err.stack })
};
}
});
app.use(router.routes());
app.use(router.allowedMethods({ throw: true }));
The router adds useful properties to the Koa context:
router.get('/users/:id', (ctx: RouterContext) => {
// URL parameters (fully typed)
const id = ctx.params.id; // string
// Router instance
const router = ctx.router;
// Matched route path
const routePath = ctx.routerPath; // => '/users/:id'
// Matched route name (if named)
const routeName = ctx.routerName; // => 'user' (if named)
// All matched layers
const matched = ctx.matched; // Array of Layer objects
// Captured values from RegExp routes
const captures = ctx.captures; // string[] | undefined
// Generate URLs
const url = ctx.router.url('user', id);
ctx.body = { id, routePath, routeName, url };
});
Extend the router context with custom properties:
import Router, { RouterContext } from '@koa/router';
import type { Next } from 'koa';
interface UserState {
user?: { id: string; email: string };
}
interface CustomContext {
requestId: string;
startTime: number;
}
const router = new Router<UserState, CustomContext>();
// Middleware that adds to context
router.use(async (ctx: RouterContext<UserState, CustomContext>, next: Next) => {
ctx.requestId = crypto.randomUUID();
ctx.startTime = Date.now();
await next();
});
router.get(
'/users/:id',
async (ctx: RouterContext<UserState, CustomContext>) => {
// All properties are fully typed
ctx.body = {
user: ctx.state.user,
requestId: ctx.requestId,
duration: Date.now() - ctx.startTime
};
}
);
Common patterns and recipes for building real-world applications with @koa/router.
See the recipes directory for complete TypeScript examples:
Each recipe file contains complete, runnable TypeScript code that you can copy and adapt to your needs.
@koa/router is designed for high performance:
Benchmarks:
# Run benchmarks
yarn benchmark
# Run all benchmark scenarios
yarn benchmark:all
@koa/router uses Node.js native test runner:
# Run all tests (core + recipes)
yarn test:all
# Run core tests only
yarn test:core
# Run recipe tests only
yarn test:recipes
# Run tests with coverage
yarn test:coverage
# Type check
yarn ts:check
# Format code with Prettier
yarn format
# Check code formatting
yarn format:check
# Lint code
yarn lint
Example test:
import { describe, it } from 'node:test';
import assert from 'node:assert';
import Koa from 'koa';
import Router from '@koa/router';
import request from 'supertest';
describe('Router', () => {
it('should route GET requests', async () => {
const app = new Koa();
const router = new Router();
router.get('/users', (ctx) => {
ctx.body = { users: [] };
});
app.use(router.routes());
const res = await request(app.callback()).get('/users').expect(200);
assert.deepStrictEqual(res.body, { users: [] });
});
});
For detailed migration information, see FULL_MIGRATION_TO_V15+.md.
Breaking Changes:
:param(regex)) are no longer supported due to path-to-regexp v8. Use validation in handlers or middleware instead.@types/@koa/router).Upgrading:
@types/@koa/router if installed (types are now included)Backward Compatibility:
The code is mostly backward compatible. If you notice any issues when upgrading, please don't hesitate to open an issue and let us know!
Contributions are welcome!
# Clone repository
git clone https://github.com/koajs/router.git
cd router
# Install dependencies (using yarn)
yarn install
# Run tests
yarn test:all
# Run tests with coverage
yarn test:coverage
# Format code
yarn format
# Check formatting
yarn format:check
# Lint code
yarn lint
# Build TypeScript
yarn build
# Type check
yarn ts:check
| Name |
|---|
| Alex Mingoia |
| @koajs |
| Imed Jaberi |
MIT © Koa.js
koa-router is another popular routing library for Koa. It provides similar functionality to @koa/router, including support for route parameters, middleware, and nested routes. However, @koa/router is a more modern and actively maintained fork of koa-router.
Express is a widely-used web framework for Node.js that includes built-in routing capabilities. While it is not specifically designed for Koa, it offers similar routing features and is known for its simplicity and flexibility. Developers who prefer a more comprehensive framework might choose Express over Koa and @koa/router.
Hapi is a rich framework for building applications and services in Node.js. It includes a powerful routing system that supports route parameters, middleware, and nested routes. Hapi is known for its configuration-driven approach and extensive plugin ecosystem, making it a strong alternative to Koa and @koa/router.
FAQs
Router middleware for koa. Maintained by Forward Email and Lad.
The npm package @koa/router receives a total of 1,277,500 weekly downloads. As such, @koa/router popularity was classified as popular.
We found that @koa/router demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Malicious dYdX client packages were published to npm and PyPI after a maintainer compromise, enabling wallet credential theft and remote code execution.
Security News
gem.coop is testing registry-level dependency cooldowns to limit exposure during the brief window when malicious gems are most likely to spread.
Security News
Following multiple malicious extension incidents, Open VSX outlines new safeguards designed to catch risky uploads earlier.