koa-router
Advanced tools
koa-router is a powerful routing middleware for Koa, a next-generation web framework for Node.js. It allows you to define routes for your web application, handle HTTP methods, and manage middleware in a clean and organized manner.
Basic Routing
This code demonstrates how to set up a basic route using koa-router. When a GET request is made to the root URL '/', it responds with 'Hello World!'.
const Koa = require('koa');
const Router = require('koa-router');
const app = new Koa();
const router = new Router();
router.get('/', (ctx, next) => {
ctx.body = 'Hello World!';
});
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(3000);Route Parameters
This code demonstrates how to use route parameters with koa-router. When a GET request is made to '/users/:id', it responds with the user ID provided in the URL.
const Koa = require('koa');
const Router = require('koa-router');
const app = new Koa();
const router = new Router();
router.get('/users/:id', (ctx, next) => {
const userId = ctx.params.id;
ctx.body = `User ID: ${userId}`;
});
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(3000);Middleware
This code demonstrates how to use middleware with koa-router. The logger middleware logs the HTTP method and URL of each request before passing control to the next middleware or route handler.
const Koa = require('koa');
const Router = require('koa-router');
const app = new Koa();
const router = new Router();
const logger = async (ctx, next) => {
console.log(`${ctx.method} ${ctx.url}`);
await next();
};
router.get('/', logger, (ctx, next) => {
ctx.body = 'Hello World!';
});
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(3000);Nested Routes
This code demonstrates how to create nested routes with koa-router. The nestedRouter handles requests to '/nested/info' and responds with 'Nested Route Info'.
const Koa = require('koa');
const Router = require('koa-router');
const app = new Koa();
const router = new Router();
const nestedRouter = new Router();
nestedRouter.get('/info', (ctx, next) => {
ctx.body = 'Nested Route Info';
});
router.use('/nested', nestedRouter.routes(), nestedRouter.allowedMethods());
app.use(router.routes());
app.use(router.allowedMethods());
app.listen(3000);Express is a fast, unopinionated, minimalist web framework for Node.js. It provides robust routing capabilities similar to koa-router but is more widely used and has a larger ecosystem of middleware and plugins.
Hapi is a rich framework for building applications and services. It provides powerful configuration-based routing and extensive support for building scalable and maintainable applications. Compared to koa-router, Hapi offers more built-in features and a more opinionated structure.
Restify is a framework specifically designed for building RESTful web services. It provides a similar routing mechanism to koa-router but is optimized for building APIs with a focus on performance and scalability.
Router middleware for koa
app.get, app.put, app.post, etc.OPTIONS requests with allowed methods.405 Method Not Allowed and 501 Not Implemented.See koa-router 7.x for koa 2.x and async/await support.
Install using npm:
npm install koa-router
RouterRouterRouterfunctionfunctionRouterLayer | falseString | ErrorStringCreate a new router.
| Param | Type | Description |
|---|---|---|
| [opts] | Object | |
| [opts.prefix] | String | prefix router paths |
Example Basic usage:
var app = require('koa')();
var router = require('koa-router')();
router.get('/', function *(next) {...});
app
.use(router.routes())
.use(router.allowedMethods());
RouterCreate router.verb() methods, where verb is one of the HTTP verbes such
as router.get() or router.post().
Match URL patterns to callback functions or controller actions using router.verb(),
where verb is one of the HTTP verbs such as router.get() or router.post().
router
.get('/', function *(next) {
this.body = 'Hello World!';
})
.post('/users', function *(next) {
// ...
})
.put('/users/:id', function *(next) {
// ...
})
.del('/users/:id', function *(next) {
// ...
});
Route paths will be translated to regular expressions using path-to-regexp.
Query strings will not be considered when matching requests.
Routes can optionally have names. This allows generation of URLs and easy renaming of URLs during development.
router.get('user', '/users/:id', function *(next) {
// ...
});
router.url('user', 3);
// => "/users/3"
Multiple middleware may be given:
router.get(
'/users/:id',
function *(next) {
this.user = yield User.findOne(this.params.id);
yield next;
},
function *(next) {
console.log(this.user);
// => { id: 17, name: "Alex" }
}
);
Nesting routers is supported:
var forums = new Router();
var posts = new Router();
posts.get('/', function *(next) {...});
posts.get('/:pid', function *(next) {...});
forums.use('/forums/:fid/posts', posts.routes(), posts.allowedMethods());
// responds to "/forums/123/posts" and "/forums/123/posts/123"
app.use(forums.routes());
Route paths can be prefixed at the router level:
var router = new Router({
prefix: '/users'
});
router.get('/', ...); // responds to "/users"
router.get('/:id', ...); // responds to "/users/:id"
Route paths can be in the wildcard format (regex):
router.get(/^\/(.*)(?:\/|$)/, ...); // match all path, e.g., /hello, /hello/world
router.get(/^\/app(?:\/|$)/, ...); // match all path that start with "/app", e.g., /app/hello, /app/hello/world
Named route parameters are captured and added to ctx.params.
router.get('/:category/:title', function *(next) {
console.log(this.params);
// => { category: 'programming', title: 'how-to-node' }
});
Kind: instance property of Router
| Param | Type | Description |
|---|---|---|
| path | String | |
| [middleware] | function | route middleware(s) |
| callback | function | route callback |
functionReturns router middleware which dispatches a route matching the request.
Kind: instance property of Router
RouterUse given middleware(s) before route callback.
Only runs if any route is matched. If a path is given, the middleware will run for any routes that include that path.
Kind: instance method of Router
| Param | Type |
|---|---|
| [path] | String |
| middleware | function |
| [...] | function |
Example
router.use(session(), authorize());
// use middleware only with given path
router.use('/users', userAuth());
app.use(router.routes());
RouterSet the path prefix for a Router instance that was already initialized.
Kind: instance method of Router
| Param | Type |
|---|---|
| prefix | String |
Example
router.prefix('/things/:thing_id')
functionReturns separate middleware for responding to OPTIONS requests with
an Allow header containing the allowed methods, as well as responding
with 405 Method Not Allowed and 501 Not Implemented as appropriate.
Kind: instance method of Router
| Param | Type | Description |
|---|---|---|
| [options] | Object | |
| [options.throw] | Boolean | throw error instead of setting status and header |
| [options.notImplemented] | Function | throw the returned value in place of the default NotImplemented error |
| [options.methodNotAllowed] | Function | throw the returned value in place of the default MethodNotAllowed error |
Example
var app = koa();
var router = router();
app.use(router.routes());
app.use(router.allowedMethods());
Example with Boom
var app = koa();
var router = router();
var Boom = require('boom');
app.use(router.routes());
app.use(router.allowedMethods({
throw: true,
notImplemented: () => new Boom.notImplemented(),
methodNotAllowed: () => new Boom.methodNotAllowed()
}));
RouterRedirect source to destination URL with optional 30x status code.
Both source and destination can be route names.
router.redirect('/login', 'sign-in');
This is equivalent to:
router.all('/login', function *() {
this.redirect('/sign-in');
this.status = 301;
});
Kind: instance method of Router
| Param | Type | Description |
|---|---|---|
| source | String | URL or route name. |
| destination | String | URL or route name. |
| code | Number | HTTP status code (default: 301). |
Layer | falseLookup route with given name.
Kind: instance method of Router
| Param | Type |
|---|---|
| name | String |
String | ErrorGenerate URL for route. Takes the route name and a map of named params.
router.get('user', '/users/:id', function *(next) {
// ...
});
router.url('user', 3);
// => "/users/3"
router.url('user', { id: 3 });
// => "/users/3"
Kind: instance method of Router
| Param | Type | Description |
|---|---|---|
| name | String | route name |
| params | Object | url parameters |
RouterRun middleware for named route parameters. Useful for auto-loading or validation.
Kind: instance method of Router
| Param | Type |
|---|---|
| param | String |
| middleware | function |
Example
router
.param('user', function *(id, next) {
this.user = users[id];
if (!this.user) return this.status = 404;
yield next;
})
.get('/users/:user', function *(next) {
this.body = this.user;
})
.get('/users/:user/friends', function *(next) {
this.body = yield this.user.getFriends();
})
// /users/3 => {"id": 3, "name": "Alex"}
// /users/3/friends => [{"id": 4, "name": "TJ"}]
StringGenerate URL from url pattern and given params.
Kind: static method of Router
| Param | Type | Description |
|---|---|---|
| path | String | url pattern |
| params | Object | url parameters |
Example
var url = Router.url('/users/:id', {id: 1});
// => "/users/1"
Please submit all issues and pull requests to the alexmingoia/koa-router repository!
Run tests using npm test.
If you have any problem or suggestion please open an issue here.
FAQs
Router middleware for koa. Maintained by Forward Email and Lad.
The npm package koa-router receives a total of 356,519 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 2 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.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.