Koa 2.0.0

Roadmap

We do not plan to release v2 as “stable” until async/await hits node.js. Requiring babel to run your server is just not good developer experience. I do this right now, and I run into a host of problems. Writing your middleware with just promises or with co() or Bluebird.coroutine() everywhere isn’t a good experience either. The current way to write middleware is ideal until async/await is native.

You can track v8’s progress on async functions here: https://bugs.chromium.org/p/v8/issues/detail?id=4483. After v8 implements async functions, it will take some time for that v8 version to hit stable (6 weeks i think, not sure), then more time for that v8 version to hit node stable (i believe they plan to release a major version every 6 months).

Thus, once async functions hit v8, we have between 2-7 months to release Koa v2 as stable, but it’ll probably just take us a day since not much other than the middeware signature has changed.

Don’t be scared to use Koa v2 Alpha right now, though. People are already using it in production, and we don’t foresee any major changes until we mark it stable.

Changes

The new middleware signature is:

// uses async arrow functions
app.use(async (ctx, next) => {
  try {
    await next() // next is now a function
  } catch (err) {
    ctx.body = { message: err.message }
    ctx.status = err.status || 500
  }
})

app.use(async ctx => {
  const user = await User.getById(this.session.userid) // await instead of yield
  ctx.body = user // ctx instead of this
})

You don’t have to use asynchronous functions - you just have to pass a function that returns a promise. A regular function that returns a promise works too!

We don’t know how much performance difference there will be, nor do many of the maintainers really care. Koa is as minimal as a framework can be and will not be your app’s bottleneck.

New Features

Hopefully, Koa v2 will not have any new features as new features can be added to v1 as well. The only new features that will be added to Koa v2 will be breaking changes. Some possible features are:

• https://github.com/koajs/koa/issues/469
• https://github.com/koajs/koa/issues/281

Features for HTTP2 support can still go into Koa v1. The only problem is that if it’s not in require('http') or require('https'), we’re not going to include it in Koa. node-spdy is probably going to be the code that is merged into node.js.

Middleware

All of the current stable versions of middleware should be targeting koa v1. If it doesn’t, let us know and we’ll fix it.

Middleware may have an “alpha” version of the koa v2 version. These should NOT be marked as stable. If they do not exist, let us know and we’ll create an alpha version so you can try it with koa v2. Better yet, make a PR!

Upgrading Middleware

You will have to convert your generators to async functions with the new middleware signature:

app.use(async ctx => {
  const user = await Users.getById(this.session.user_id)
  ctx.body = { message: 'some message' }
})

Upgrading your middleware may be a pain in the ass. One migration path is to update them one-by-one.

1. Wrap all your current middleware in koa-convert
2. Test
3. npm outdated to see which koa middleware is outdated
4. Update one outdated middleware, remove using koa-convert
5. Test
6. Repeat steps 3-5 until you’re done

We have plans to create a migration bot #625 to make this process slightly better.

Updating Your Code

You should start refactoring your code now to ease migrating to Koa v2:

• Return promises everywhere!
• Do not use yield*
• Do not use yield {} or yield [].
  • Convert yield [] into yield Promise.all([])
  • Convert yield {} into yield Bluebird.props({})

You could also refactor your logic outside of Koa middleware functions. Create functions like function* someLogic(ctx) {} and call it in your middleware as const result = yield someLogic(this). Not using this will help migrations to the new middleware signature, which does not use this.

I currently use babel and use async functions + flow type outside of koa middleware. this will make my migration path in the future easier. I’m not sure if I plan to ever remove babel though since I really like flow type.

How You Can Help

• Documentation - we need a lot!
• Testing Koa v2 and its corresponding middleware
• Help create the migration bot https://github.com/koajs/koa/issues/625

Questions

• Should we transpile w/ babel before we publish? It might make performance better as it transpiles down to ES5, which V8 is more optimized with. Anyone wanna try benchmarking it?

[italoacasas]

Hi everyone. I’m going to be releasing Node.js 7.6.0 RC next week, with v8 5.5 (async/await)…

[jonathanong]

https://github.com/koajs/koa/commit/6c6aa4dab41bd3d11a62afe5de9fc144f9b2add3 😃