Koa is a new web framework designed by the team behind Express, which aims to be a smaller, more expressive, and more robust foundation for web applications and APIs. By leveraging async functions, Koa allows you to ditch callbacks and greatly increase error-handling. Koa does not bundle any middleware within its core, and it provides an elegant suite of methods that make writing servers fast and enjoyable.
Koa requires node v7.6.0 or higher for ES2015 and async function support.
You can quickly install a supported version of node with your favorite version manager:
$ nvm install 7
$ npm i koa
$ node my-koa-app.js
To use async
functions in Koa in versions of node < 7.6, we recommend using babel’s require hook.
require('babel-register');
// require the rest of the app that needs to be transpiled after the hook
const app = require('./app');
To parse and transpile async functions, you should at a minimum have the transform-async-to-generator or transform-async-to-module-method plugins. For example, in your .babelrc
file, you should have:
{
"plugins": ["transform-async-to-generator"]
}
You can also use the env preset with a target option "node": "current"
instead.
A Koa application is an object containing an array of middleware functions which are composed and executed in a stack-like manner upon request. Koa is similar to many other middleware systems that you may have encountered such as Ruby’s Rack, Connect, and so on - however a key design decision was made to provide high level “sugar” at the otherwise low-level middleware layer. This improves interoperability, robustness, and makes writing middleware much more enjoyable.
This includes methods for common tasks like content-negotiation, cache freshness, proxy support, and redirection among others. Despite supplying a reasonably large number of helpful methods Koa maintains a small footprint, as no middleware are bundled.
The obligatory hello world application:
const Koa = require('koa');
const app = new Koa();
app.use(async ctx => {
ctx.body = 'Hello World';
});
app.listen(3000);
Koa middleware cascade in a more traditional way as you may be used to with similar tools - this was previously difficult to make user friendly with node’s use of callbacks. However with async functions we can achieve “true” middleware. Contrasting Connect’s implementation which simply passes control through series of functions until one returns, Koa invoke “downstream”, then control flows back “upstream”.
The following example responds with “Hello World”, however first the request flows through the x-response-time
and logging
middleware to mark when the request started, then continue to yield control through the response middleware. When a middleware invokes next()
the function suspends and passes control to the next middleware defined. After there are no more middleware to execute downstream, the stack will unwind and each middleware is resumed to perform its upstream behaviour.
const Koa = require('koa');
const app = new Koa();
// logger
app.use(async (ctx, next) => {
await next();
const rt = ctx.response.get('X-Response-Time');
console.log(`${ctx.method} ${ctx.url} - ${rt}`);
});
// x-response-time
app.use(async (ctx, next) => {
const start = Date.now();
await next();
const ms = Date.now() - start;
ctx.set('X-Response-Time', `${ms}ms`);
});
// response
app.use(async ctx => {
ctx.body = 'Hello World';
});
app.listen(3000);
Application settings are properties on the app
instance, currently the following are supported:
app.env
defaulting to the NODE_ENV or “development”app.proxy
when true proxy header fields will be trustedapp.subdomainOffset
offset of .subdomains
to ignore [2]A Koa application is not a 1-to-1 representation of an HTTP server. One or more Koa applications may be mounted together to form larger applications with a single HTTP server.
Create and return an HTTP server, passing the given arguments to Server#listen()
. These arguments are documented on nodejs.org. The following is a useless Koa application bound to port 3000
:
const Koa = require('koa');
const app = new Koa();
app.listen(3000);
The app.listen(...)
method is simply sugar for the following:
const http = require('http');
const Koa = require('koa');
const app = new Koa();
http.createServer(app.callback()).listen(3000);
This means you can spin up the same application as both HTTP and HTTPS or on multiple addresses:
const http = require('http');
const https = require('https');
const Koa = require('koa');
const app = new Koa();
http.createServer(app.callback()).listen(3000);
https.createServer(app.callback()).listen(3001);
Return a callback function suitable for the http.createServer()
method to handle a request. You may also use this callback function to mount your Koa app in a Connect/Express app.
Add the given middleware function to this application. See Middleware for more information.
Set signed cookie keys.
These are passed to KeyGrip, however you may also pass your own KeyGrip
instance. For example the following are acceptable:
app.keys = ['im a newer secret', 'i like turtle'];
app.keys = new KeyGrip(['im a newer secret', 'i like turtle'], 'sha256');
These keys may be rotated and are used when signing cookies with the { signed: true }
option:
ctx.cookies.set('name', 'tobi', { signed: true });
app.context
is the prototype from which ctx
is created. You may add additional properties to ctx
by editing app.context
. This is useful for adding properties or methods to ctx
to be used across your entire app, which may be more performant (no middleware) and/or easier (fewer require()
s) at the expense of relying more on ctx
, which could be considered an anti-pattern.
For example, to add a reference to your database from ctx
:
app.context.db = db();
app.use(async ctx => {
console.log(ctx.db);
});
Note:
ctx
are defined using getters, setters, and Object.defineProperty()
. You can only edit these properties (not recommended) by using Object.defineProperty()
on app.context
. See https://github.com/koajs/koa/issues/652.ctx
and settings. Thus, mounted apps are really just groups of middleware.By default outputs all errors to stderr unless app.silent
is true
. The default error handler also won’t output errors when err.status
is 404
or err.expose
is true
. To perform custom error-handling logic such as centralized logging you can add an “error” event listener:
app.on('error', err => {
log.error('server error', err)
});
If an error is in the req/res cycle and it is not possible to respond to the client, the Context
instance is also passed:
app.on('error', (err, ctx) => {
log.error('server error', err, ctx)
});
When an error occurs and it is still possible to respond to the client, aka no data has been written to the socket, Koa will respond appropriately with a 500 “Internal Server Error”. In either case an app-level “error” is emitted for logging purposes.
A Koa Context encapsulates node’s request
and response
objects into a single object which provides many helpful methods for writing web applications and APIs. These operations are used so frequently in HTTP server development that they are added at this level instead of a higher level framework, which would force middleware to re-implement this common functionality.
A Context
is created per request, and is referenced in middleware as the receiver, or the ctx
identifier, as shown in the following snippet:
app.use(async ctx => {
ctx; // is the Context
ctx.request; // is a Koa Request
ctx.response; // is a Koa Response
});
Many of the context’s accessors and methods simply delegate to their ctx.request
or ctx.response
equivalents for convenience, and are otherwise identical. For example ctx.type
and ctx.length
delegate to the response
object, and ctx.path
and ctx.method
delegate to the request
.
Context
specific methods and accessors.
Node’s request
object.
Node’s response
object.
Bypassing Koa’s response handling is not supported. Avoid using the following node properties:
res.statusCode
res.writeHead()
res.write()
res.end()
A Koa Request
object.
A Koa Response
object.
The recommended namespace for passing information through middleware and to your frontend views.
ctx.state.user = await User.find(id);
Application instance reference.
Get cookie name
with options
:
signed
the cookie requested should be signedKoa uses the cookies module where options are simply passed.
Set cookie name
to value
with options
:
maxAge
a number representing the milliseconds from Date.now() for expirysigned
sign the cookie valueexpires
a Date
for cookie expirationpath
cookie path, /'
by defaultdomain
cookie domainsecure
secure cookiehttpOnly
server-accessible cookie, true by defaultoverwrite
a boolean indicating whether to overwrite previously set cookies of the same name (false by default). If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie.Koa uses the cookies module where options are simply passed.
Helper method to throw an error with a .status
property defaulting to 500
that will allow Koa to respond appropriately. The following combinations are allowed:
ctx.throw(400);
ctx.throw(400, 'name required');
ctx.throw(400, 'name required', { user: user });
For example ctx.throw(400, 'name required')
is equivalent to:
const err = new Error('name required');
err.status = 400;
err.expose = true;
throw err;
Note that these are user-level errors and are flagged with err.expose
meaning the messages are appropriate for client responses, which is typically not the case for error messages since you do not want to leak failure details.
You may optionally pass a properties
object which is merged into the error as-is, useful for decorating machine-friendly errors which are reported to the requester upstream.
ctx.throw(401, 'access_denied', { user: user });
Koa uses http-errors to create errors.
Helper method to throw an error similar to .throw()
when !value
. Similar to node’s assert() method.
ctx.assert(ctx.state.user, 401, 'User not found. Please login!');
Koa uses http-assert for assertions.
To bypass Koa’s built-in response handling, you may explicitly set ctx.respond = false;
. Use this if you want to write to the raw res
object instead of letting Koa handle the response for you.
Note that using this is not supported by Koa. This may break intended functionality of Koa middleware and Koa itself. Using this property is considered a hack and is only a convenience to those wishing to use traditional fn(req, res)
functions and middleware within Koa.
The following accessors and alias Request equivalents:
ctx.header
ctx.headers
ctx.method
ctx.method=
ctx.url
ctx.url=
ctx.originalUrl
ctx.origin
ctx.href
ctx.path
ctx.path=
ctx.query
ctx.query=
ctx.querystring
ctx.querystring=
ctx.host
ctx.hostname
ctx.fresh
ctx.stale
ctx.socket
ctx.protocol
ctx.secure
ctx.ip
ctx.ips
ctx.subdomains
ctx.is()
ctx.accepts()
ctx.acceptsEncodings()
ctx.acceptsCharsets()
ctx.acceptsLanguages()
ctx.get()
The following accessors and alias Response equivalents:
ctx.body
ctx.body=
ctx.status
ctx.status=
ctx.message
ctx.message=
ctx.length=
ctx.length
ctx.type=
ctx.type
ctx.headerSent
ctx.redirect()
ctx.attachment()
ctx.set()
ctx.append()
ctx.remove()
ctx.lastModified=
ctx.etag=
A Koa Request
object is an abstraction on top of node’s vanilla request object, providing additional functionality that is useful for every day HTTP server development.
Request header object.
Set request header object.
Request header object. Alias as request.header
.
Set request header object. Alias as request.header=
.
Request method.
Set request method, useful for implementing middleware such as methodOverride()
.
Return request Content-Length as a number when present, or undefined
.
Get request URL.
Set request URL, useful for url rewrites.
Get request original URL.
Get origin of URL, include protocol
and host
.
ctx.request.origin
// => http://example.com
Get full request URL, include protocol
, host
and url
.
// => http://example.com/foo/bar?q=1
Get request pathname.
Set request pathname and retain query-string when present.
Get raw query string void of ?
.
Set raw query string.
Get raw query string with the ?
.
Set raw query string.
Get host (hostname:port) when present. Supports X-Forwarded-Host
when app.proxy
is true, otherwise Host
is used.
Get hostname when present. Supports X-Forwarded-Host
when app.proxy
is true, otherwise Host
is used.
If host is IPv6, Koa delegates parsing to WHATWG URL API, Note This may impact performance.
Get WHATWG parsed URL object.
Get request Content-Type
void of parameters such as “charset”.
const ct = ctx.request.type;
// => "image/png"
Get request charset when present, or undefined
:
ctx.request.charset;
// => "utf-8"
Get parsed query-string, returning an empty object when no query-string is present. Note that this getter does not support nested parsing.
For example “color=blue&size=small”:
{
color: 'blue',
size: 'small'
}
Set query-string to the given object. Note that this setter does not support nested objects.
Check if a request cache is “fresh”, aka the contents have not changed. This method is for cache negotiation between If-None-Match
/ ETag
, and If-Modified-Since
and Last-Modified
. It should be referenced after setting one or more of these response headers.
// freshness check requires status 20x or 304
ctx.status = 200;
ctx.set('ETag', '123');
// cache is ok
if (ctx.fresh) {
ctx.status = 304;
return;
}
// cache is stale
// fetch new data
ctx.body = await db.find('something');
Inverse of request.fresh
.
Return request protocol, “https” or “http”. Supports X-Forwarded-Proto
when app.proxy
is true.
Shorthand for ctx.protocol == "https"
to check if a request was issued via TLS.
Request remote address. Supports X-Forwarded-For
when app.proxy
is true.
When X-Forwarded-For
is present and app.proxy
is enabled an array of these ips is returned, ordered from upstream -> downstream. When disabled an empty array is returned.
Return subdomains as an array.
Subdomains are the dot-separated parts of the host before the main domain of the app. By default, the domain of the app is assumed to be the last two parts of the host. This can be changed by setting app.subdomainOffset
.
For example, if the domain is “tobi.ferrets.example.com”: If app.subdomainOffset
is not set, ctx.subdomains
is ["ferrets", "tobi"]
. If app.subdomainOffset
is 3, ctx.subdomains
is ["tobi"]
.
Check if the incoming request contains the “Content-Type” header field, and it contains any of the give mime type
s. If there is no request body, null
is returned. If there is no content type, or the match fails false
is returned. Otherwise, it returns the matching content-type.
// With Content-Type: text/html; charset=utf-8
ctx.is('html'); // => 'html'
ctx.is('text/html'); // => 'text/html'
ctx.is('text/*', 'text/html'); // => 'text/html'
// When Content-Type is application/json
ctx.is('json', 'urlencoded'); // => 'json'
ctx.is('application/json'); // => 'application/json'
ctx.is('html', 'application/*'); // => 'application/json'
ctx.is('html'); // => false
For example if you want to ensure that only images are sent to a given route:
if (ctx.is('image/*')) {
// process
} else {
ctx.throw(415, 'images only!');
}
Koa’s request
object includes helpful content negotiation utilities powered by accepts and negotiator. These utilities are:
request.accepts(types)
request.acceptsEncodings(types)
request.acceptsCharsets(charsets)
request.acceptsLanguages(langs)
If no types are supplied, all acceptable types are returned.
If multiple types are supplied, the best match will be returned. If no matches are found, a false
is returned, and you should send a 406 "Not Acceptable"
response to the client.
In the case of missing accept headers where any type is acceptable, the first type will be returned. Thus, the order of types you supply is important.
Check if the given type(s)
is acceptable, returning the best match when true, otherwise false
. The type
value may be one or more mime type string such as “application/json”, the extension name such as “json”, or an array ["json", "html", "text/plain"]
.
// Accept: text/html
ctx.accepts('html');
// => "html"
// Accept: text/*, application/json
ctx.accepts('html');
// => "html"
ctx.accepts('text/html');
// => "text/html"
ctx.accepts('json', 'text');
// => "json"
ctx.accepts('application/json');
// => "application/json"
// Accept: text/*, application/json
ctx.accepts('image/png');
ctx.accepts('png');
// => false
// Accept: text/*;q=.5, application/json
ctx.accepts(['html', 'json']);
ctx.accepts('html', 'json');
// => "json"
// No Accept header
ctx.accepts('html', 'json');
// => "html"
ctx.accepts('json', 'html');
// => "json"
You may call ctx.accepts()
as many times as you like, or use a switch:
switch (ctx.accepts('json', 'html', 'text')) {
case 'json': break;
case 'html': break;
case 'text': break;
default: ctx.throw(406, 'json, html, or text only');
}
Check if encodings
are acceptable, returning the best match when true, otherwise false
. Note that you should include identity
as one of the encodings!
// Accept-Encoding: gzip
ctx.acceptsEncodings('gzip', 'deflate', 'identity');
// => "gzip"
ctx.acceptsEncodings(['gzip', 'deflate', 'identity']);
// => "gzip"
When no arguments are given all accepted encodings are returned as an array:
// Accept-Encoding: gzip, deflate
ctx.acceptsEncodings();
// => ["gzip", "deflate", "identity"]
Note that the identity
encoding (which means no encoding) could be unacceptable if the client explicitly sends identity;q=0
. Although this is an edge case, you should still handle the case where this method returns false
.
Check if charsets
are acceptable, returning the best match when true, otherwise false
.
// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
ctx.acceptsCharsets('utf-8', 'utf-7');
// => "utf-8"
ctx.acceptsCharsets(['utf-7', 'utf-8']);
// => "utf-8"
When no arguments are given all accepted charsets are returned as an array:
// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
ctx.acceptsCharsets();
// => ["utf-8", "utf-7", "iso-8859-1"]
Check if langs
are acceptable, returning the best match when true, otherwise false
.
// Accept-Language: en;q=0.8, es, pt
ctx.acceptsLanguages('es', 'en');
// => "es"
ctx.acceptsLanguages(['en', 'es']);
// => "es"
When no arguments are given all accepted languages are returned as an array:
// Accept-Language: en;q=0.8, es, pt
ctx.acceptsLanguages();
// => ["es", "pt", "en"]
Check if the request is idempotent.
Return the request socket.
Return request header.
A Koa Response
object is an abstraction on top of node’s vanilla response object, providing additional functionality that is useful for every day HTTP server development.
Response header object.
Response header object. Alias as response.header
.
Request socket.
Get response status. By default, response.status
is set to 404
unlike node’s res.statusCode
which defaults to 200
.
Set response status via numeric code:
NOTE: don’t worry too much about memorizing these strings, if you have a typo an error will be thrown, displaying this list so you can make a correction.
Get response status message. By default, response.message
is associated with response.status
.
Set response status message to the given value.
Set response Content-Length to the given value.
Return response Content-Length as a number when present, or deduce from ctx.body
when possible, or undefined
.
Get response body.
Set response body to one of the following:
string
writtenBuffer
writtenStream
pipedObject
|| Array
json-stringifiednull
no content responseIf response.status
has not been set, Koa will automatically set the status to 200
or 204
.
The Content-Type is defaulted to text/html or text/plain, both with a default charset of utf-8. The Content-Length field is also set.
The Content-Type is defaulted to application/octet-stream, and Content-Length is also set.
The Content-Type is defaulted to application/octet-stream.
Whenever a stream is set as the response body, .onerror
is automatically added as a listener to the error
event to catch any errors. In addition, whenever the request is closed (even prematurely), the stream is destroyed. If you do not want these two features, do not set the stream as the body directly. For example, you may not want this when setting the body as an HTTP stream in a proxy as it would destroy the underlying connection.
See: https://github.com/koajs/koa/pull/612 for more information.
Here’s an example of stream error handling without automatically destroying the stream:
const PassThrough = require('stream').PassThrough;
app.use(async ctx => {
ctx.body = someHTTPStream.on('error', ctx.onerror).pipe(PassThrough());
});
The Content-Type is defaulted to application/json. This includes plain objects { foo: 'bar' }
and arrays ['foo', 'bar']
.
Get a response header field value with case-insensitive field
.
const etag = ctx.response.get('ETag');
Set response header field
to value
:
Append additional header field
with value val
.
ctx.append('Link', '<http://127.0.0.1/>');
Set several response header fields
with an object:
ctx.set({
'Etag': '1234',
'Last-Modified': date
});
Remove header field
.
Get response Content-Type
void of parameters such as “charset”.
const ct = ctx.type;
// => "image/png"
Set response Content-Type
via mime string or file extension.
ctx.type = 'text/plain; charset=utf-8';
ctx.type = 'image/png';
ctx.type = '.png';
ctx.type = 'png';
Note: when appropriate a charset
is selected for you, for example response.type = 'html'
will default to “utf-8”. If you need to overwrite charset
, use ctx.set('Content-Type', 'text/html')
to set response header field to value directly.
Very similar to ctx.request.is()
. Check whether the response type is one of the supplied types. This is particularly useful for creating middleware that manipulate responses.
For example, this is a middleware that minifies all HTML responses except for streams.
const minify = require('html-minifier');
app.use(async (ctx, next) => {
await next();
if (!ctx.response.is('html')) return;
let body = ctx.body;
if (!body || body.pipe) return;
if (Buffer.isBuffer(body)) body = body.toString();
ctx.body = minify(body);
});
Perform a [302] redirect to url
.
The string “back” is special-cased to provide Referrer support, when Referrer is not present alt
or “/” is used.
ctx.redirect('back');
ctx.redirect('back', '/index.html');
ctx.redirect('/login');
ctx.redirect('http://google.com');
To alter the default status of 302
, simply assign the status before or after this call. To alter the body, assign it after this call:
ctx.status = 301;
ctx.redirect('/cart');
ctx.body = 'Redirecting to shopping cart';
Set Content-Disposition
to “attachment” to signal the client to prompt for download. Optionally specify the filename
of the download.
Check if a response header has already been sent. Useful for seeing if the client may be notified on error.
Return the Last-Modified
header as a Date
, if it exists.
Set the Last-Modified
header as an appropriate UTC string. You can either set it as a Date
or date string.
ctx.response.lastModified = new Date();
Set the ETag of a response including the wrapped "
s. Note that there is no corresponding response.etag
getter.
ctx.response.etag = crypto.createHash('md5').update(ctx.body).digest('hex');
Vary on field
.
Flush any set headers, and begin the body.
#koa #node #javascript #web-development