What is koa-router?
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.
What are koa-router's main functionalities?
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);
Other packages similar to koa-router
express
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
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
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.
koa-router
Router middleware for koa
- Express-style routing using
app.get
, app.put
, app.post
, etc. - Named URL parameters and regexp captures.
- String or regular expression route matching.
- Named routes with URL generation.
- Responds to
OPTIONS
requests with allowed methods. - Support for
405 Method Not Allowed
and 501 Not Implemented
. - Multiple route middleware.
- Multiple routers.
Installation
Install using npm:
npm install koa-router
API Reference
Router() ⏏
Create a new router.
Example
Basic usage:
var app = require('koa')();
var router = require('koa-router')();
router.get('/', function *(next) {...});
app
.use(router.routes())
.use(router.allowedMethods());
Or if you prefer to extend the app with router methods:
var app = require('koa')();
var router = require('koa-router');
app
.use(router(app))
.get('/', function *(next) {...});
router.get|put|post|patch|delete ⇒ Router
Create 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 used to match requests.
Query strings will not be considered when matching requests.
Named routes
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);
Multiple middleware
Multiple middleware may be given and are composed using
koa-compose:
router.get(
'/users/:id',
function *(next) {
this.user = yield User.findOne(this.params.id);
yield next;
},
function *(next) {
console.log(this.user);
}
);
URL parameters
Named route parameters are captured and added to ctx.params
.
Named parameters
router.get('/:category/:title', function *(next) {
console.log(this.params);
});
Parameter middleware
Run middleware for named route parameters. Useful for auto-loading or
validation.
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;
})
Regular expressions
Control route matching exactly by specifying a regular expression instead of
a path string when creating the route. For example, it might be useful to match
date formats for a blog, such as /blog/2013-09-04
:
router.get(/^\/blog\/\d{4}-\d{2}-\d{2}\/?$/i, function *(next) {
});
Capture groups from regular expression routes are added to
ctx.captures
, which is an array.
Param | Type | Description |
---|
path | String | RegExp | |
[middleware] | function | route middleware(s) |
callback | function | route callback |
router.routes ⇒ function
Returns router middleware which dispatches a route matching the request.
router.use(middleware, [...]) ⇒ Router
Use given middleware(s) before route callback.
Param | Type |
---|
middleware | function |
[...] | function |
Example
router.use(session(), authorize());
app.use(router.routes());
router.allowedMethods([options]) ⇒ function
Returns 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.
router.allowedMethods()
is automatically mounted if the router is created
with app.use(router(app))
. Create the router separately if you do not want
to use .allowedMethods()
, or if you are using multiple routers.
Param | Type | Description |
---|
[options] | Object | |
[options.throw] | Boolean | throw error instead of setting status and header |
Example
var app = koa();
var router = router();
app.use(router.routes());
app.use(router.allowedMethods());
router.all(name, path, [middleware], callback) ⇒ Router
Register route with all methods.
Param | Type | Description |
---|
name | String | Optional. |
path | String | RegExp | |
[middleware] | function | You may also pass multiple middleware. |
callback | function | |
router.redirect(source, destination, code) ⇒ Router
Redirect 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;
});
Param | Type | Description |
---|
source | String | URL, RegExp, or route name. |
destination | String | URL or route name. |
code | Number | HTTP status code (default: 301). |
router.route(name) ⇒ Route
| false
Lookup route with given name
.
router.url(name, params) ⇒ String
| Error
Generate URL for route. Takes either map of named params
or series of
arguments (for regular expression routes).
router.get('user', '/users/:id', function *(next) {
});
router.url('user', 3);
router.url('user', { id: 3 });
Param | Type | Description |
---|
name | String | route name |
params | Object | url parameters |
router.param(param, middleware) ⇒ Router
Run middleware for named route parameters. Useful for auto-loading or
validation.
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;
})
Contributing
Please submit all issues and pull requests to the alexmingoia/koa-router repository!
Tests
Run tests using npm test
.
Support
If you have any problem or suggestion please open an issue here.