Last Updated: February 25, 2016

oh hurrow Koa.js

Koa is a node.js web framework that is more modern than express. We will build a functional web server in this tutorial. Koa takes advantage of es6 features, like generators. Generators do not actually generate anything. Read that article to get a gist (hint yield statements matter). I'll be here when you get back.

Welcome back! To use this we need the newest version of node. Check with:

$ node -v
v0.12.7

Then to run our es6 code with $ node --harmony server.js. To not type that --harmony flag all the time add an alias to ~/.bash_profile:

alias node="node --harmony"
alias nodemon="nodemon --harmony"

Harmony means ES6. Nodemon is for nodemon.

Start project

$ mkdir project-name
$ cd project-name && npm init
$ npm install koa koa-route --save

Make a simple server.js:

var koa = require('koa');
var route = require('koa-route');
var app = koa();

// routes
app.use(route.get('/', index));
app.use(route.get('/about', about));

// es6 generators expected as arguments
function *index() {
    // this is a Koa Context
    // A Koa Context encapsulates node’s request and response objects into a single object 
    this.body = "<h1>Hello Koa!</h1>";
}

function *about() {
    console.log('Koa Context (this) has these properties: ');
    console.log(Object.keys(this));
    this.body = "<h2>This is the about route</h2>";
}

app.listen(8008);
console.log('Koa listening on port 8008');

Here we see the es6 generators. Route callbacks expect generators, not regular functions. this in the generator is special in koa. It contains request and response as well as some other handy bits for web apps. When you hit the /about route you will see this:

Koa Context (this) has these properties: 
[ 'request',
  'response',
  'app',
  'req',
  'res',
  'onerror',
  'originalUrl',
  'cookies',
  'accept',
  'state' ]

Okay little different, nothing crazy. Next up we want to render some template files. ejs will be our template engine. co-views has some config options for using jade or swig.. whatever that is.

$ npm install co-views ejs --save

Then in server.js add:

var render = views(__dirname + '/views', { ext: 'ejs' });

...

function *index() {
    this.body = yield render('index', {});
}

This is similar to express. The empty object is data we can pass to the template engine. co-body acts like body-parser for incoming input so add that too.

$ npm install co-body --save