Have ideas to improve npm?Join in the discussion! »


    2.10.1 • Public • Published


    This is a tiny (improved) fork of Koa that is almost 80% smaller in disc space and uses a lot less dependancies, a total of 4 packages compared to Koa's 42 package installation. It also uses some improved versions to some of the previous dependencies. Overall the whole installation can be expected to go from 807KB to around 160KB.

    Breaking change:

    One of the core mechanic was removed from the core as it should be found in a middleware instead (in my opinion) and that would be ctx.cookies() as I never found myself using cookies ever in all my projects.

    Koa middleware framework for nodejs

    gitter NPM version build status PR's Welcome

    What is Koa

    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-lite

    Hello Koa

    const Koa = require('koa-lite');
    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.
    • 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+)

    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`);

    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.

    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.

    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 and jonathanong to disclose.


    See AUTHORS.





    npm i koa-lite

    DownloadsWeekly Downloads






    Unpacked Size

    78.2 kB

    Total Files


    Last publish


    • avatar