2013-12-22 06:41:06 +00:00
< img src = "https://dl.dropboxusercontent.com/u/6396913/koa/logo.png" alt = "koa middleware framework for nodejs" width = "255px" / >
2014-12-04 09:03:46 +00:00
2014-11-30 08:03:09 +00:00
[![gitter][gitter-image]][gitter-url]
2014-07-26 06:43:41 +00:00
[![NPM version][npm-image]][npm-url]
[![build status][travis-image]][travis-url]
2014-07-06 01:32:25 +00:00
[![Test coverage][coveralls-image]][coveralls-url]
2017-02-26 07:57:49 +00:00
[![OpenCollective Backers][backers-image]](#backers)
[![OpenCollective Sponsors][sponsors-image]](#sponsors)
2013-11-08 09:16:26 +00:00
2015-11-25 03:51:14 +00:00
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.
2013-08-17 07:15:57 +00:00
2015-11-05 16:42:14 +00:00
Only methods that are common to nearly all HTTP servers are integrated directly into Koa's small ~570 SLOC codebase. This
2015-08-23 15:18:54 +00:00
includes things like content negotiation, normalization of node inconsistencies, redirection, and a few others.
2013-08-17 07:15:57 +00:00
2015-08-31 05:07:54 +00:00
Koa is not bundled with any middleware.
2013-08-17 07:15:57 +00:00
## Installation
2017-02-25 06:30:11 +00:00
Koa requires __node v7.6.0__ or higher for ES2015 and async function support.
2013-08-17 07:15:57 +00:00
```
2017-02-25 06:30:11 +00:00
$ npm install koa
2013-08-17 07:15:57 +00:00
```
2015-11-25 03:51:14 +00:00
## Hello koa
2013-08-17 07:15:57 +00:00
2015-11-25 03:51:14 +00:00
```js
const Koa = require('koa');
const app = new Koa();
2013-08-17 07:15:57 +00:00
2015-11-25 03:51:14 +00:00
// response
app.use(ctx => {
ctx.body = 'Hello Koa';
});
app.listen(3000);
```
2013-08-17 07:15:57 +00:00
2014-08-04 15:34:07 +00:00
## Getting started
2014-07-26 06:43:41 +00:00
2014-12-04 09:03:46 +00:00
- [Kick-Off-Koa ](https://github.com/koajs/kick-off-koa ) - An intro to koa via a set of self-guided workshops.
- [Workshop ](https://github.com/koajs/workshop ) - A workshop to learn the basics of koa, Express' spiritual successor.
- [Introduction Screencast ](http://knowthen.com/episode-3-koajs-quickstart-guide/ ) - An introduction to installing and getting started with Koa
2014-07-26 06:43:41 +00:00
2015-11-25 03:51:14 +00:00
## Middleware
2016-05-13 06:27:18 +00:00
Koa is a middleware framework that can take 3 different kinds of functions as middleware:
2015-11-25 03:51:14 +00:00
* common function
* async function
2017-02-25 18:59:55 +00:00
* generator function
2015-11-25 03:51:14 +00:00
2016-05-13 06:27:18 +00:00
Here is an example of logger middleware with each of the different functions:
2015-11-25 03:51:14 +00:00
2017-02-25 06:30:11 +00:00
### ___async___ functions (node v7.6+)
```js
app.use(async (ctx, next) => {
const start = new Date();
await next();
const ms = new Date() - start;
console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
});
```
2015-11-25 03:51:14 +00:00
### Common function
2015-10-23 08:36:13 +00:00
2016-03-15 15:35:52 +00:00
```js
2016-05-13 06:27:18 +00:00
// 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.
2015-10-23 08:36:13 +00:00
app.use((ctx, next) => {
2016-03-15 15:35:52 +00:00
const start = new Date();
2015-10-23 08:36:13 +00:00
return next().then(() => {
2016-03-15 15:35:52 +00:00
const ms = new Date() - start;
2015-11-07 17:09:58 +00:00
console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
2015-10-23 08:36:13 +00:00
});
});
```
2015-11-25 03:51:14 +00:00
### GeneratorFunction
2015-10-23 08:36:13 +00:00
To use generator functions, you must use a wrapper such as [co ](https://github.com/tj/co ) that is no longer supplied with Koa.
```js
2016-03-15 15:35:52 +00:00
app.use(co.wrap(function *(ctx, next) {
const start = new Date();
2015-10-23 08:36:13 +00:00
yield next();
2016-03-15 15:35:52 +00:00
const ms = new Date() - start;
2015-11-07 17:09:58 +00:00
console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
2015-10-23 08:36:13 +00:00
}));
```
2016-03-14 14:51:14 +00:00
### Old signature middleware (v1.x) - Deprecated
2015-10-29 17:25:46 +00:00
2016-03-14 14:51:14 +00:00
**Old signature middleware (v1.x) support will be removed in v3**
Koa v2.x will try to convert legacy signature, generator middleware on `app.use` , using [koa-convert ](https://github.com/koajs/convert ).
It is however recommended that you choose to migrate all v1.x middleware as soon as possible.
```js
// Koa will convert
app.use(function *(next) {
const start = new Date();
yield next;
const ms = new Date() - start;
console.log(`${this.method} ${this.url} - ${ms}ms`);
});
```
You could do it manually as well, in which case Koa will not convert.
2013-08-17 07:15:57 +00:00
```js
2016-03-15 15:35:52 +00:00
const convert = require('koa-convert');
2013-08-17 07:15:57 +00:00
2016-03-15 15:35:52 +00:00
app.use(convert(function *(next) {
const start = new Date();
2013-11-08 00:31:16 +00:00
yield next;
2016-03-15 15:35:52 +00:00
const ms = new Date() - start;
2015-11-07 17:09:58 +00:00
console.log(`${this.method} ${this.url} - ${ms}ms`);
2015-10-29 17:25:46 +00:00
}));
2015-11-25 03:51:14 +00:00
```
2013-08-17 07:15:57 +00:00
2015-11-25 03:51:14 +00:00
## Babel setup
2016-07-23 17:48:20 +00:00
2017-02-25 06:30:11 +00:00
For Node 4.0+ and Babel 6.0 you can setup like this:
2015-11-25 03:51:14 +00:00
```bash
2016-08-06 05:06:31 +00:00
$ npm install babel-register babel-plugin-transform-async-to-generator --save
2013-08-17 07:15:57 +00:00
```
2015-11-25 03:51:14 +00:00
```js
// set babel in entry file
2016-07-23 17:48:20 +00:00
require('babel-register')({
plugins: ['transform-async-to-generator']
2015-11-25 03:51:14 +00:00
});
```
2016-07-23 17:48:20 +00:00
Check out an example in koa's [test ](test/babel/index.js ).
2015-11-25 03:51:14 +00:00
2013-08-17 07:15:57 +00:00
## Running tests
```
$ make test
```
2013-08-26 02:16:57 +00:00
## Authors
2015-10-12 07:04:58 +00:00
See [AUTHORS ](AUTHORS ).
2013-08-26 02:16:57 +00:00
2015-11-25 03:51:14 +00:00
## Community
- [API ](docs/api/index.md ) documentation
- [Badgeboard ](https://koajs.github.io/badgeboard ) and list of official modules
- [Examples ](https://github.com/koajs/examples )
- [Middleware ](https://github.com/koajs/koa/wiki ) list
- [Wiki ](https://github.com/koajs/koa/wiki )
- [G+ Community ](https://plus.google.com/communities/101845768320796750641 )
2016-03-15 19:38:42 +00:00
- [Reddit Community ](https://www.reddit.com/r/koajs )
2015-11-25 03:51:14 +00:00
- [Mailing list ](https://groups.google.com/forum/#!forum/koajs )
- [Guide ](docs/guide.md )
- [FAQ ](docs/faq.md )
2016-03-15 19:38:42 +00:00
- [中文文档 ](https://github.com/guo-yu/koa-guide )
2015-11-25 03:51:14 +00:00
- __[#koajs]__ on freenode
2016-06-14 01:53:25 +00:00
## Backers
2017-02-26 07:57:49 +00:00
Support us with a monthly donation and help us continue our activities.
2016-06-14 01:53:25 +00:00
< a href = "https://opencollective.com/koajs/backer/0/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/0/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/1/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/1/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/2/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/2/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/3/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/3/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/4/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/4/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/5/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/5/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/6/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/6/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/7/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/7/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/8/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/8/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/9/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/9/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/10/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/10/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/11/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/11/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/12/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/12/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/13/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/13/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/14/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/14/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/15/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/15/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/16/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/16/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/17/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/17/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/18/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/18/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/19/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/19/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/20/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/20/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/21/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/21/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/22/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/22/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/23/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/23/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/24/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/24/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/25/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/25/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/26/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/26/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/27/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/27/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/28/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/28/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/backer/29/website" target = "_blank" > < img src = "https://opencollective.com/koajs/backer/29/avatar.svg" > < / a >
## Sponsors
2017-02-26 07:57:49 +00:00
Become a sponsor and get your logo on our README on Github with a link to your site.
2016-06-14 01:53:25 +00:00
< a href = "https://opencollective.com/koajs/sponsor/0/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/0/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/1/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/1/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/2/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/2/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/3/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/3/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/4/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/4/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/5/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/5/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/6/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/6/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/7/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/7/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/8/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/8/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/9/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/9/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/10/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/10/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/11/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/11/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/12/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/12/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/13/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/13/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/14/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/14/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/15/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/15/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/16/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/16/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/17/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/17/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/18/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/18/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/19/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/19/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/20/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/20/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/21/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/21/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/22/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/22/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/23/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/23/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/24/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/24/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/25/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/25/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/26/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/26/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/27/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/27/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/28/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/28/avatar.svg" > < / a >
< a href = "https://opencollective.com/koajs/sponsor/29/website" target = "_blank" > < img src = "https://opencollective.com/koajs/sponsor/29/avatar.svg" > < / a >
2013-08-17 07:15:57 +00:00
# License
MIT
2014-07-06 01:32:25 +00:00
2014-10-09 17:59:57 +00:00
[npm-image]: https://img.shields.io/npm/v/koa.svg?style=flat-square
2016-03-15 19:38:42 +00:00
[npm-url]: https://www.npmjs.com/package/koa
2014-10-27 16:42:01 +00:00
[travis-image]: https://img.shields.io/travis/koajs/koa/master.svg?style=flat-square
2014-07-06 01:32:25 +00:00
[travis-url]: https://travis-ci.org/koajs/koa
2017-02-26 07:57:49 +00:00
[coveralls-image]: https://img.shields.io/codecov/c/github/koajs/koa.svg?style=flat-square
2016-03-03 22:40:43 +00:00
[coveralls-url]: https://codecov.io/github/koajs/koa?branch=master
2017-02-26 07:57:49 +00:00
[backers-image]: https://opencollective.com/koajs/backers/badge.svg?style=flat-square
[sponsors-image]: https://opencollective.com/koajs/sponsors/badge.svg?style=flat-square
[gitter-image]: https://img.shields.io/gitter/room/koajs/koa.svg?style=flat-square
2014-11-04 16:59:11 +00:00
[gitter-url]: https://gitter.im/koajs/koa?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge& utm_content=badge
2015-10-05 23:22:56 +00:00
[#koajs]: https://webchat.freenode.net/?channels=#koajs