Koa v3 Tracker

[jonathanong]

Starting a new tracker for v3

Milestone: https://github.com/koajs/koa/milestone/4

Other Breaking Changes:

• rewrite to ES modules
• adjust naming to WHATWG standards https://nodejs.org/api/url.html#url_url_strings_and_url_objects
• rename raw http requests? koa 3.0 roadmap #1114 (comment)
• officially support the http2 module

Future:

• Deno support
• Bun support
• Rewrite in TypeScript

Tests:

• Migrate to jest
• Properly close down server after each test run

Improved Documentation:

• how to serve http/https/http2
• example of how to use expect-continue
• How to sent Content-Length on a HEAD response #1827
• How to use SSE with Koa? #1774 SSE example with AI chat

[jaydenseric]

Regarding the goal to move to Jest; please don't. Use the native Node.js test runner! It should be more than adequate.

You can pair it with coverage-node, a very lightweight CLI tool, to enforce 100% code coverage in tests:

https://github.com/jaydenseric/coverage-node

[talentlessguy]

to add, Node test runner has identical API to Jest

for assertion, node:assert could be used

[benmccann]

Vitest is another fairly lightweight option for jest-compatible test runner. My last experience was that Jest is terrible to use with ESM as it doesn't fully support it yet. vitest is much better in this regard.

A rewrite might also be a nice time to take a look at including only minimal dependencies (e.g. https://npmgraph.js.org/?q=koa vs https://npmgraph.js.org/?q=polka)

[jonathanong]

I just realized that I already migrated it to jest a while go haha. if anyone is interested in migrating to node's official test runner, that would be great. otherwise, I will leave it as is

[titanism]

I just pinned this issue. Also I merged a core bug fix just a bit ago at #1593 which fixes #1547 – tldr; HEAD requests with http2 server instance were broken and not working.

[titanism]

👍 to c8 https://www.npmjs.com/package/c8 and Node's native testing
👍 to using np for releases

[jonathanong]

Just need to spend time to write a migration doc for v3 and then I am going to launch it

[jrnail23]

I know this is blasphemy these days, so at the risk of sounding like a luddite, I have to beg you, PLEASE, PLEASE don't convert Koa to ESM-Only unless you'll be actively updating/patching the v2 branch for an extended period of time (like multiple years).

Migrating existing NodeJS codebases to ESM still isn't effortless, and going to ESM-only risks leaving CJS users in a vulnerable state where they can't safely upgrade to incorporate security patches and critical bug fixes.

[talentlessguy]

I know this is blasphemy these days, so at the risk of sounding like a luddite, I have to beg you, PLEASE, PLEASE don't convert Koa to ESM-Only unless you'll be actively updating/patching the v2 branch for an extended period of time (like multiple years).

Migrating existing NodeJS codebases to ESM still isn't effortless, and going to ESM-only risks leaving CJS users in a vulnerable state where they can't safely upgrade to incorporate security patches and critical bug fixes.

why would you want to migrate existing codebases to a semver incompatible version of a web framework without upgrading Node.js?

starting version 20.x you can require(esm) so in case you're on that version, you can safely use Koa as ESM

[jonathanong]

let me know if anyone contributed that I missed in the release notes https://github.com/koajs/koa/releases/tag/v3.0.0

[TechQuery]

let me know if anyone contributed that I missed in the release notes https://github.com/koajs/koa/releases/tag/v3.0.0

@jonathanong I have a big thank for your hard working, but I'm worried about how many popular middlewares will be broken by this major upgrading, do we have a draft list in the latest migration guide?

[jonathanong]

@TechQuery it should just be send or any middleware that serves from the filesystem due to the ENOENT removal, I will take a look later

[jonathanong]

actually, send handles ENOENT itself. looks like tests are passing with koa@3 so we're good

[titanism]

Koa v3.0 was featured in Node Weekly today at https://nodeweekly.com/issues/576 as was our @forwardemail blog post https://forwardemail.net/en/blog/docs/how-npm-packages-billion-downloads-shaped-javascript-ecosystem 🚀