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
- koa-router
- Router ⏏
- new Router([app], [opts])
- instance
- .get|put|post|patch|delete ⇒
Router
- .routes ⇒
function
- .use(middleware, [...]) ⇒
Router
- .prefix(prefix) ⇒
Router
- .allowedMethods([options]) ⇒
function
- .all(name, path, [middleware], callback) ⇒
Router
- .redirect(source, destination, code) ⇒
Router
- .register(name, path, methods, middleware) ⇒
Route
- .route(name) ⇒
Route
| false
- .url(name, params) ⇒
String
| Error
- .param(param, middleware) ⇒
Router
- static
Router ⏏
Kind: Exported class
new Router([app], [opts])
Create a new router.
Param | Type | Description |
---|
[app] | koa.Application | extend koa app with router methods |
[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());
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);
}
);
Router prefixes
Route paths can be prefixed at the router level:
var router = new Router({
prefix: '/users'
});
router.get('/', ...);
router.get('/:id', ...);
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.
Kind: instance property of Router
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.
Kind: instance property of Router
router.use(middleware, [...]) ⇒ Router
Use given middleware(s) before route callback. Only runs if any route is
matched.
Kind: instance method of Router
Param | Type |
---|
middleware | function |
[...] | function |
Example
router.use(session(), authorize());
app.use(router.routes());
router.prefix(prefix) ⇒ Router
Set the path prefix for a Router instance that was already initialized.
Kind: instance method of Router
Example
router.prefix('/things/:thing_id')
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.
Kind: instance method of Router
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.
Kind: instance method of Router
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;
});
Kind: instance method of Router
Param | Type | Description |
---|
source | String | URL, RegExp, or route name. |
destination | String | URL or route name. |
code | Number | HTTP status code (default: 301). |
router.register(name, path, methods, middleware) ⇒ Route
Create and register a route.
Kind: instance method of Router
Param | Type | Description |
---|
name | String | Optional. |
path | String | RegExp | Path string or regular expression. |
methods | Array.<String> | Array of HTTP verbs. |
middleware | function | Multiple middleware also accepted. |
router.route(name) ⇒ Route
| false
Lookup route with given name
.
Kind: instance method of Router
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 });
Kind: instance method of Router
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.
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;
})
Router.url(path, params) ⇒ String
Generate 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});
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.