Expressive HTTP middleware framework for node.js to make web applications and APIs more enjoyable to write. Koa's middleware stack flows in a stack-like manner, allowing you to perform actions downstream then filter and manipulate the response upstream.
Only methods that are common to nearly all HTTP servers are integrated directly into Koa's small ~570 SLOC codebase. This includes things like content negotiation, normalization of node inconsistencies, redirection, and a few others.
Koa is not bundled with any middleware.
Koa requires node v7.6.0 or higher for ES2015 and async function support.
$ npm install koa
const Koa = ;const app = ;// responseapp;app;
- Kick-Off-Koa - An intro to Koa via a set of self-guided workshops.
- Workshop - A workshop to learn the basics of Koa, Express' spiritual successor.
- Introduction Screencast - An introduction to installing and getting started with Koa
Koa is a middleware framework that can take two different kinds of functions as middleware:
- async function
- common function
Here is an example of logger middleware with each of the different functions:
async functions (node v7.6+)
// Middleware normally takes two parameters (ctx, next), ctx is the context for one request,// next is a function that is invoked to execute the downstream middleware. It returns a Promise with a then function for running code after completion.app;
Koa v1.x Middleware Signature
The middleware signature changed between v1.x and v2.x. The older signature is deprecated.
Old signature middleware support will be removed in v3
Please see the Migration Guide for more information on upgrading from v1.x and using v1.x middleware with v2.x.
Context, Request and Response
Each middleware receives a Koa
Context object that encapsulates an incoming
http message and the corresponding response to that message.
ctx is often used
as the parameter name for the context object.
Koa provides a
Request object as the
request property of the
Request object provides helpful methods for working with
http requests which delegate to an IncomingMessage
from the node
Here is an example of checking that a requesting client supports xml.
Koa provides a
Response object as the
response property of the
Response object provides helpful methods for working with
http responses which delegate to a ServerResponse
Koa's pattern of delegating to Node's request and response objects rather than extending them
provides a cleaner interface and reduces conflicts between different middleware and with Node
itself as well as providing better support for stream handling. The
IncomingMessage can still be
directly accessed as the
req property on the
ServerResponse can be directly
accessed as the
res property on the
Here is an example using Koa's
Response object to stream a file as the response body.
Context object also provides shortcuts for methods on its
response. In the prior
ctx.type can be used instead of
ctx.accepts can be used
The object created when executing
new Koa() is known as the Koa application object.
The application object is Koa's interface with node's http server and handles the registration of middleware, dispatching to the middleware from http, default error handling, as well as configuration of the context, request and response objects.
Learn more about the application object in the Application API Reference.
If you're not using
node v7.6+, we recommend setting up
$ npm install @babel/register @babel/preset-env @babel/cli --save-dev
In development, you'll want to use
node --require @babel/register <your-entry-file>
In production, you'll want to build your files with
@babel/cli. Suppose you are compiling a folder
src and you wanted the output to go to a new folder
babel src --out-dir dist --copy-files
And have your
$ npm test
- Badgeboard and list of official modules
- Middleware list
- Reddit Community
- Mailing list
- 中文文档 v1.x
- 中文文档 v2.x
- #koajs on freenode
Looking for a career upgrade?
Support us with a monthly donation and help us continue our activities.
Become a sponsor and get your logo on our README on Github with a link to your site.