koa README

The project's README from github.com/koajs/koa. As one markdown file: README.md.

Koa middleware framework for nodejs

gitter 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.

Installation

Koa requires node v18.0.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';
});

app.listen(3000);

Getting started

Middleware

Koa is a middleware framework that can take two different kinds of functions as middleware:

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 has been removed in v3

Please see the Migration Guide from v2.x to v3.x for information on upgrading from v2.x to v3.x, and the Migration Guide from v1.x to v2.x for information on upgrading from v1.x to 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.

Documentation

Troubleshooting

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.

Authors

See AUTHORS.

Community

Backers

Support us with a monthly donation and help us continue our activities.

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site.

License

MIT

koa (koajs/koa)

Searching Database…

35.7K ·GitHub
Koa
What is this?Koa is an expressive HTTP middleware framework for Node.js built on ES2017 async functions, designed to make writing web apps and APIs more enjoyable.
Is it a full framework like Express, or something more minimal?It's a minimal core: only methods common to nearly all HTTP servers are built in (content negotiation, redirection, etc.), and Koa ships with no bundled middleware at all — you add what you need.
How do I get a basic app running?Install the koa package, then create an app with 'new Koa()', add middleware functions, and call app.listen() — the README shows a minimal 'Hello Koa' example.
What Node.js version do I need?You need Node.js v18.0.0 or higher for ES2015/async function support.
Can I use the old v1.x middleware style?No — the old generator-based v1.x middleware signature is deprecated and support for it was fully removed in v3, so you must migrate to the async function signature.
Who is this for compared to Express users?It's aimed at Node.js developers who want a lighter, more composable alternative to Express; there's even a dedicated 'Koa for Express Users' guide to ease the transition.
How does middleware flow through the stack?Koa's middleware stack flows in a stack-like manner: each middleware runs code downstream, then the response is filtered and manipulated upstream as control returns back through the chain.
What is the ctx object?Every middleware receives a Koa Context object (commonly named ctx) that encapsulates both the incoming HTTP request and the corresponding response, with Request and Response helper objects accessible via ctx.request and ctx.response.
Does Koa extend Node's req/res objects?No, instead of extending Node's IncomingMessage and ServerResponse, Koa delegates to them through its own Request/Response objects, giving a cleaner interface and reducing middleware conflicts; the raw objects remain accessible as ctx.req and ctx.res.
What are similar projects?express, multer, fiber, apollo-server, node-restify, ktor, axum, egg
Which topics is it in?koa, node-js, middleware, express, async, web-framework, http, rest-api, backend, web-development, framework, npm
Creator
koajs
Size
3.9 MB
Stars
35.7K
Updated
CommitOct 09Releasev3.2.1May 21
Age
13y
Commits · 90 Days