node package manager



a simple encapsulation for koa2, you can use it to build your minimal web server.

npm version


$ npm install koa-next --save

make sure your node version > 7.6.0

start a server

const koa = require('koa-next');
const path = require('path');
  watch: true, // to make auto-reload, default false
  base: __dirname, // base dir
  path: {
    middleware: path.join(__dirname, 'middleware'), // middleware folder
    controller: path.join(__dirname, 'controller'), // controller folder
    service: path.join(__dirname, 'service') //service folder

what are middleware controller & service ?

The diff between koa-next & koa2 is koa-next uses three-type handlers to make our coding happier.


just the same as the koa's middleware

every request will pass all the middlewares set here. u can add logger, login and other handle request funs here. ex,

module.exports = async function m1 (ctx, next) {`path is ${ctx.path}`);
  await next();

every request will log due to this middleware. of course, it must under the middleware folder.


you can set your handlers to handle specific path request, ex, suppose below is the profile.js under controller folder.

module.exports = [
    method: 'get',
    url: '/profile/:name',
    controller: async (ctx) => {
      ctx.body = `u are visiting ${} home page`;
    method: 'post',
    url: '/profile/annoymous',
    controller: async (ctx) => {
      ctx.body = `not found this person`;

when u visit /profile/pony, u can get 'u are visiting pony home page' on your browser, and visit '/profile/annoymous', 'not found this person' comes.

koa-next will pass the params at ctx.params, just as :name above.

Each fragment of the url, delimited by a /, can have the following signature:

  • string - ex /post

  • string|string - | separated strings, ex /post|page

  • :name - Wildcard route matched to a name

  • (regex) - A regular expression match without saving the parameter (not recommended)

  • :name(regex) - Named regular expression match


you can set it to add fun at ctx. ex,

module.exports = function (ctx) {
  return {
    json(data) {
      ctx.type = 'application/json';
      ctx.body = JSON.stringify(data, null, 2);

suppose the fileName of this code is simpleResponse.js under the service folder.

u can use this at your controller, ex,

    url: '/profile/annoymous',
    controller: async (ctx) => {
      await ctx.simpleResponse.json({user: 'annoymous'});

when u are visting /profile/annoymous, u will set the json type response quickly.


  1. every time you modify your services, middlewares and controllers, koa-next will auto-reload without restart, have fun.

  2. u can add $config.js under middleware folder to custom your middlewares' invoke order, ex,

module.exports = {
  order: ['m2.js', 'm1.js'],
  except: ['m4.js']

the m2.js will be ahead of m1.js at every request, and m4.js will be not invoked.

  1. u can set specific middlewares for one controller, add middlewares property at your controller. ex, if u wanna to get a body content from POST method, u can add koa-body middleware at this controller.
  url: '/',
  method: post,
  middlewares: requre('koa-body')({formidable:{uploadDir: __dirname}}), 
  controller: async (ctx) => {

these middlewares only impact this controller.

  1. u can also add middlewares at your config, ex,
  middleware | middlewares: Function | Function <Array> 
  1. u can use handlebars at your service like example.


see /example to start it.

see also