Introduction to Koa2: Features, History, and Basic Usage

Because of a recent project, the author started learning the Koa2 framework and wrote this article to help newcomers get started.

Why choose Koa2?

Koa2 is small, robust, and expressive, even smaller than Express.

Full support for ES6/ES7 syntax.

Elegant structure, easy to extend; major frameworks like 360's ThinkJS and Alibaba's Egg.js are built on Koa2, and the core source code is only about four files (~500 lines).

In 2018, the learning wave for Koa2 has already arrived.

Node.js Web Framework Evolution

In the early days, Node.js only provided raw HTTP capabilities, so developers had to implement many features themselves (“no wheels”). Express emerged as the most popular framework, offering a full‑stack of middleware (routing, body parsing, etc.). Later, TJ Holowaychuk created Koa to address the callback‑hell problem of Express. Koa’s middleware follows an onion/stack model (first‑in‑last‑out) rather than a simple sequential chain.

Subsequent generations include Koa2, which adds async/await support, and enterprise‑level frameworks such as 360's ThinkJS and Alibaba's Egg.js (built on Koa2).

Key Differences Between Express and Koa

Both provide similar capabilities, but Koa organizes functionality into a single ctx object that contains request and response , replacing Express's separate req and res .

Koa’s middleware is based on async/await and follows the onion model, offering better flow control (e.g., logging).

Koa2 Positioning

Smaller, more robust, and more expressive.

Avoids repetitive callback nesting.

Greatly improves error‑handling efficiency.

Lightweight and elegant, providing only the essential web‑service functions.

Extensible via middleware for advanced needs.

Koa2 requires Node.js v7.6.0 or higher to support ES2015 and async functions.

Basic Syntax Overview

Creating an application instance:

const Koa = require('koa');
const app = new Koa();

Registering middleware (the function passed to app.use() is the simplest middleware):

app.use(async (ctx, next) => {
  console.log('Request received');
  await next();
  console.log('Response sent');
});

The middleware executes in an onion fashion: the first registered middleware is the outermost layer, and the last is the innermost.

Routing

Koa2 does not include a router by default; you can add one, for example koa-router :

const Router = require('koa-router');
const router = new Router();
router.get('/hello', async ctx => {
  ctx.body = 'Hello World';
});
app.use(router.routes());

Static File Service

Static assets can be served via middleware such as koa-static :

const serve = require('koa-static');
app.use(serve('./public'));

Server‑Side Rendering (SSR)

Install view middleware and a template engine (e.g., EJS) to enable SSR:

# npm install --save koa-views ejs

Then configure the view engine in Koa.

Database Operations

MongoDB and MySQL can be accessed through their respective Node.js drivers or ODM/ORM libraries (e.g., mongoose for MongoDB, sequelize for MySQL) within Koa middleware.

In summary, Koa2 offers a modern, async‑oriented approach to building web services, with a minimal core and powerful extensibility via middleware. The ecosystem is mature as of 2018, with many large companies adopting it.

Reference materials:

https://chenshenhai.github.io/koa2-note/

https://zhuanlan.zhihu.com/p/26216336

https://dongliang1993.github.io/2017/12/06/koa2-%E6%BA%90%E7%A0%81%E5%88%86%E6%9E%90-%E4%B8%80/

https://juejin.im/post/5a6dda1d5188257330612d88