Document which babel presets/plugins are required
wheresrhys opened this issue · 12 comments
Since the latest version of Babel stating 'Babel required' in the koa docs is no longer meaningful as by default it does nothing, and you have to configure which syntax it should transpile. At the very least koa needs to document which plugins are required. Even better would be a table indicating which plugins are required for given environments (e.g. none are needed for koa 1 on node 4, but very many are needed for koa 2 on 0.12... I'm currently struggling to figure out what babel transforms are needed to run koa 2 on node 5)
https://github.com/koajs/koa/blob/master/docs/api/index.md#async-functions-with-babel
sorry we haven't updated the website yet!
also, koa 2 is node@4+. i guess if you wanted it on 0.12, you would just also use es2015
Thanks for the pointer. It turns out I had chosen the right transform, but still struggling to get koa2 working. I get the following error:
if (isGeneratorFunction(fn)) throw new TypeError('Support for generators has been removed. See the documentation for examples of how to convert old middleware https://github.com/koajs/koa#example-with-old-signature');
Looking at the koa src this kinda makes sense - async is converted to generator, which koa2 explicitly prohibits from being used - but how do I stop it happening? To I need to have babel-core transpile koa too?
Ah no, figured it out now. I needed to wrap koa-static and koa-router in koa-convert
You can use the preset stage-3 to enable async functions in Babel.
For koa@2.0 with async syntax
| node version | babel preset |
|---|---|
| 5.0 | es2015-node5, stage-3 |
| 4.0 | preset: es2015-node5, stage-3. plugin: es2015-spread |
| 0.12 | es2015, stage3 |
Technically you just need an async transformer, I have an example in the koa-socket repo using just the async-to-generator transform and node 4.
Any of the other stuff is project specific, not koa specific.
yep, you just need the transformer. the presets contain much more-- you may want these, but you 100% don't need them to use Koa with async functions if you have node 4+.
forgive the plug, but if you're using Node 5.x and are specifically building server-side stuff (i.e. not webpack'ing front-end assets), check out my node5 preset for babel
It has async/await.
I've just used @leebenson's preset for a project, works flawlessly! Its not minimal requirement for Koa but very useful nonetheless.
thanks @mattstyles - I've literally just this second bumped the version, too.
they are in the v2 docs. let me know how we can improve it, but we can close it for now.
yes, there's a lot of presets you can use, but the last thing we want to do is add them all to the docs :)