Koa is a lightweight web framework for Node.js, designed to be a smaller, more expressive, and more robust foundation for web applications and APIs. It was created by the team behind Express, the most popular web framework for Node.js, and aims to be a smaller, more expressive, and more robust foundation for web applications and APIs. Koa uses async functions to handle requests, allowing you to eliminate callbacks and greatly increase error-handling. It also has a suite of middleware that allows you to perform tasks like parsing request bodies, handling cookies, and more. Koa aims to be a more expressive and minimalistic alternative to Express, with a focus on providing just the tools you need to build web applications and APIs.

NPM downloads

Github stars

Github forks

Number of contributors

Number of contributors 30 days







Number of Contributors


Number of days since last commit


Top contributors all time

TJ Holowaychuk345
Jonathan Ong215
Yiyu He31
Tejas Manohar21
Martin Iwanowski13
Julian Gruber10
Konstantin Vyatkin10
Slobodan Stojanovic10
Lee Bousfield7
Michaël Zasso5
Rui Marinho5
Douglas Wade4

Top contributors last 30 days



Koa middleware framework for nodejs

NPM version
build status
Test coverage
OpenCollective Backers
OpenCollective Sponsors
PR's Welcome

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 v12.17.0 or higher for ES2015 and async function support.

$ npm install koa

Hello Koa

const Koa = require('koa');
const app = new Koa();

// response
app.use(ctx => {
  ctx.body = 'Hello Koa';


Getting started

  • Kick-Off-Koa - An intro to Koa via a set of self-guided workshops.
  • Guide - Go straight to the docs.


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+)

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);

Common function

// 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.use((ctx, next) => {
  const start = Date.now();
  return next().then(() => {
    const ms = Date.now() - start;
    console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);

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.

app.use(async (ctx, next) => { await next(); });

Koa provides a Request object as the request property of the Context.
Koa's Request object provides helpful methods for working with
http requests which delegate to an IncomingMessage
from the node http module.

Here is an example of checking that a requesting client supports xml.

app.use(async (ctx, next) => {
  ctx.assert(ctx.request.accepts('xml'), 406);
  // equivalent to:
  // if (!ctx.request.accepts('xml')) ctx.throw(406);
  await next();

Koa provides a Response object as the response property of the Context.
Koa's 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 Context and ServerResponse can be directly
accessed as the res property on the Context.

Here is an example using Koa's Response object to stream a file as the response body.

app.use(async (ctx, next) => {
  await next();
  ctx.response.type = 'xml';
  ctx.response.body = fs.createReadStream('really_large.xml');

The Context object also provides shortcuts for methods on its request and response. In the prior
examples, ctx.type can be used instead of ctx.response.type and ctx.accepts can be used
instead of ctx.request.accepts.

For more information on Request, Response and Context, see the Request API Reference,
Response API Reference and Context API Reference.

Koa Application

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.



Check the Troubleshooting Guide or Debugging Koa in
the general Koa guide.

Running tests

$ npm test

Reporting vulnerabilities

To report a security vulnerability, please do not open an issue, as this notifies attackers of the vulnerability. Instead, please email dead_horse, jonathanong, and niftylettuce to disclose.




Job Board

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.