koa-lite/docs/migration.md

134 lines
3.9 KiB
Markdown
Raw Normal View History

# Migrating from Koa v1.x to v2.x
## New middleware signature
Koa v2 introduces a new signature for middleware.
**Old signature middleware (v1.x) support will be removed in v3**
The new middleware signature is:
```js
// 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!
The signature has changed to pass `Context` via an explicit parameter, `ctx` above, instead of via
`this`. The context passing change makes koa more compatible with es6 arrow functions, which capture `this`.
## Using v1.x Middleware in v2.x
Koa v2.x will try to convert legacy signature, generator middleware on `app.use`, using [koa-convert](https://github.com/koajs/convert).
It is however recommended that you choose to migrate all v1.x middleware as soon as possible.
```js
// Koa will convert
app.use(function *(next) {
const start = new Date();
yield next;
const ms = new Date() - start;
console.log(`${this.method} ${this.url} - ${ms}ms`);
});
```
You could do it manually as well, in which case Koa will not convert.
```js
const convert = require('koa-convert');
app.use(convert(function *(next) {
const start = new Date();
yield next;
const ms = new Date() - start;
console.log(`${this.method} ${this.url} - ${ms}ms`);
}));
```
## Upgrading middleware
You will have to convert your generators to async functions with the new middleware signature:
```js
app.use(async ctx => {
const user = await Users.getById(this.session.user_id);
await next();
ctx.body = { message: 'some message' };
})
```
Upgrading your middleware may require some work. 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
## 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`.
## Application object constructor requires new
In v1.x, the Application constructor function could be called directly, without `new` to
instantiate an instance of an application. For example:
```js
var koa = require('koa');
var app = module.exports = koa();
```
v2.x uses es6 classes which require the `new` keyword to be used.
```js
var koa = require('koa');
var app = module.exports = new koa();
```
## ENV specific logging behavior removed
An explicit check for the `test` environment was removed from error handling.
## Dependency changes
- [co](https://github.com/tj/co) is no longer bundled with Koa. Require or import it directly.
- [composition](https://github.com/thenables/composition) is no longer used and deprecated.
## v1.x support
The v1.x branch is still supported but should not receive feature updates. Except for this migration
guide, documentation will target the latest version.
## Help out
If you encounter migration related issues not covered by this migration guide, please consider
submitting a documentation pull request.