koa-lite/Readme.md

205 lines
14 KiB
Markdown
Raw Permalink Normal View History

<img src="https://dl.dropboxusercontent.com/u/6396913/koa/logo.png" alt="koa middleware framework for nodejs" width="255px" />
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]
[![Test coverage][coveralls-image]][coveralls-url]
[![OpenCollective Backers][backers-image]](#backers)
[![OpenCollective Sponsors][sponsors-image]](#sponsors)
2013-11-08 09:16:26 +00:00
2016-07-06 15:47:25 +00:00
Expressive, light-weight HTTP framework for node.js to make web applications and APIs more enjoyable to write. Koa requests flow through middleware in a stack-like manner, allowing you to perform actions downstream then filter and manipulate the response upstream. Koa's use of generators also greatly increases the readability and robustness of your application.
2013-08-17 07:15:57 +00:00
Only methods that are common to nearly all HTTP servers are integrated directly into Koa's small ~550 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
2016-07-06 15:47:25 +00:00
Koa is not bundled with any middleware, but there is a [large collection](https://github.com/koajs/koa/wiki) of community middleware to choose from.
2013-08-17 07:15:57 +00:00
## Installation
```
$ npm install koa
```
2016-01-18 00:27:23 +00:00
Koa is supported in node v4+ and node v0.12 with the `--harmony-generators` or `--harmony` flag.
2016-03-22 17:50:59 +00:00
## Koa v2
2016-01-18 00:27:23 +00:00
2016-03-22 17:50:59 +00:00
Koa v2 is currently released with the `next` tag (meaning it will not be marked as latest).
You can install it with semver:
```bash
npm install koa@2
```
2016-07-25 22:12:08 +00:00
In this new version, the middleware function signature changes to adopt async/await:
2016-01-18 00:27:23 +00:00
```js
// Koa application is now a class and requires the new operator.
const app = new Koa();
2016-01-18 00:27:23 +00:00
// uses async arrow functions
app.use(async (ctx, next) => {
try {
await next(); // next is now a function
2016-01-18 00:27:23 +00:00
} catch (err) {
ctx.body = { message: err.message };
ctx.status = err.status || 500;
2016-01-18 00:27:23 +00:00
}
});
2016-01-18 00:27:23 +00:00
app.use(async ctx => {
const user = await User.getById(ctx.session.userid); // await instead of yield
ctx.body = user; // ctx instead of this
});
2016-01-18 00:27:23 +00:00
```
2016-03-22 17:50:59 +00:00
2016-07-25 22:12:08 +00:00
Until async/await is natively supported in Node Koa 1.x is the official release, however you may wish to adopt 2.x early by using Babel to compile. Koa 1.x generator-based middleware may be "upgraded" to the 2.x flavour using [koa-convert](https://github.com/koajs/convert).
2016-03-22 17:50:59 +00:00
To learn more about Koa v2, follow [this issue](https://github.com/koajs/koa/issues/533) or read the docs here: https://github.com/koajs/koa/tree/v2.x/docs.
2013-08-17 07:15:57 +00:00
## Community
- [API](docs/api/index.md) documentation
2014-09-08 00:42:30 +00:00
- [Badgeboard](https://koajs.github.io/badgeboard) and list of official modules
2013-12-07 23:09:09 +00:00
- [Examples](https://github.com/koajs/examples)
2013-11-12 09:43:27 +00:00
- [Middleware](https://github.com/koajs/koa/wiki) list
2013-09-17 13:48:36 +00:00
- [Wiki](https://github.com/koajs/koa/wiki)
2013-08-17 07:15:57 +00:00
- [G+ Community](https://plus.google.com/communities/101845768320796750641)
- [Reddit Community](https://www.reddit.com/r/koajs)
2013-08-17 07:15:57 +00:00
- [Mailing list](https://groups.google.com/forum/#!forum/koajs)
2013-09-03 01:25:17 +00:00
- [Guide](docs/guide.md)
2013-08-21 05:07:00 +00:00
- [FAQ](docs/faq.md)
- [中文文档](https://github.com/guo-yu/koa-guide)
- __[#koajs]__ on freenode
2013-08-17 07:15:57 +00:00
## Getting started
2014-07-26 06:43:41 +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
2013-08-17 07:15:57 +00:00
## Example
```js
var koa = require('koa');
var app = koa();
// logger
2013-11-08 00:31:16 +00:00
app.use(function *(next){
var start = new Date;
yield next;
var ms = new Date - start;
console.log('%s %s - %s', this.method, this.url, ms);
2013-08-17 07:15:57 +00:00
});
// response
2013-11-08 00:31:16 +00:00
app.use(function *(){
this.body = 'Hello World';
2013-08-17 07:15:57 +00:00
});
app.listen(3000);
```
## Running tests
```
$ make test
```
2013-08-26 02:16:57 +00:00
## Authors
2014-11-07 08:12:10 +00:00
- [TJ Holowaychuk](https://github.com/tj)
2013-08-26 02:16:57 +00:00
- [Jonathan Ong](https://github.com/jonathanong)
2013-11-08 00:31:16 +00:00
- [Julian Gruber](https://github.com/juliangruber)
- [Yiyu He](https://github.com/dead-horse)
2013-08-26 02:16:57 +00:00
## Backers
Support us with a monthly donation and help us continue our activities.
<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
Become a sponsor and get your logo on our README on Github with a link to your site.
<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-10-09 17:59:57 +00:00
[npm-image]: https://img.shields.io/npm/v/koa.svg?style=flat-square
[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
[travis-url]: https://travis-ci.org/koajs/koa
2016-03-15 10:27:09 +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
[backers-image]: https://opencollective.com/koajs/backers/badge.svg?style=flat-square
[sponsors-image]: https://opencollective.com/koajs/sponsors/badge.svg?style=flat-square
2016-03-15 10:27:09 +00:00
[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
[#koajs]: https://webchat.freenode.net/?channels=#koajs