Github url

koa

by koajs

koajs /koa

Expressive middleware for node.js using ES2017 async functions

29.6K Stars 2.8K Forks Last release: Not found MIT License 1.1K Commits 91 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Koa middleware framework for nodejs

gitterNPM versionbuild statusTest coverageOpenCollective BackersOpenCollective SponsorsPR'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 v7.6.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

  • 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

Middleware

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

Babel setup

If you're not using

node v7.6+

, we recommend setting up

babel

with [

@babel/preset-env

](https://babeljs.io/docs/en/next/babel-preset-env):

$ npm install @babel/register @babel/preset-env @babel/cli --save-dev

In development, you'll want to use [

@babel/register

](https://babeljs.io/docs/en/next/babel-register):

node --require @babel/register <your-entry-file>
</your-entry-file>

In production, you'll want to build your files with [

@babel/cli

](https://babeljs.io/docs/en/babel-cli). Suppose you are compiling a folder

src

and you wanted the output to go to a new folder

dist

with non-javascript files copied:

babel src --out-dir dist --copy-files

And have your

.babelrc

setup:

{ "presets": [["@babel/preset-env", { "targets": { "node": true } }] ] }

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

Authors

See AUTHORS.

Community

Job Board

Looking for a career upgrade?

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.