Koa.js 3.0 was officially released! Since the development plan was launched in 2017, after an 8-year long run, the classic lightweight web framework created by the original team of Express finally returned to the spotlight in a new guise. Koa 3.0 is not only a leap in version number, but also an important milestone in the modernization process of Node.js.

What Are the Major Updates in Koa 3.0?

Minimum Support for Node.js v18, Embracing New Features

Koa 3.0 has raised the minimum Node.js version to v18, fully leveraging the performance and security advantages of the modern V8 engine. For developers, this means they can safely use new features such as the native Fetch API and node:test, making the project foundation more stable.

// Now you can directly use fetch in a Koa 3.0 project
const response = await fetch("https://api.example.com/data");
const data = await response.json();

There is no need to introduce a third-party fetch library as fetch is built into Node.js v18+.

Completely Say Goodbye to Generator, Fully Adopting async/await

Remember the Generator in the Koa 1.x era? Koa 3.0 has completely removed support for Generator, and all middleware must be based on async/await. This not only makes asynchronous flow control more intuitive but also brings the code style in perfect alignment with modern JavaScript.

// Koa 1.x
app.use(function* (next) {
  yield next;
  this.body = "Hello Koa 1.x";
});
// Koa 3.0
app.use(async (ctx, next) => {
  await next();
  ctx.body = "Hello Koa 3.0";
});

Native Support for WHATWG Response Bodies, More Unified Front-end and Back-end

The new version supports WHATWG-standard response body objects (such as Blob and FormData), enabling seamless 对接 between Koa and the browser-side Fetch API. Full-stack developers no longer have to worry about data format conversion, and front-end and back-end collaboration becomes smoother.

// Code Explanation
import { Blob } from "buffer";
app.use(async (ctx) => {
  ctx.body = new Blob(["Hello, Koa 3.0!"]);
});

By directly returning WHATWG-standard objects, the data formats between the front-end and back-end are consistent, greatly enhancing the development experience!

Upgraded Streaming Response Capability, Supporting Custom Streams

Koa 3.0 supports directly using custom Node.js streams as response bodies, significantly improving the transmission efficiency in scenarios such as large files, audio, and video. Whether it's packing a zip with archiver or handling large-scale data streams, it can be easily coped with.

// Code Explanation
import archiver from 'archiver';
const archive = archiver('zip');
// Assume there is a large file stream
const stream =...;
archive.append(stream, { name: 'archive.zip' });
res.body = archive;

You can directly assign a Node.js stream object to ctx.body to achieve efficient streaming transmission.

AsyncLocalStorage, Accessing Request Context Anytime

Was it always troublesome to access ctx (context) outside middleware before? Now with app.currentContext, no matter where you are, you can access the context information of the current request at any time. Integrating utility functions, logging, and third-party libraries becomes more elegant and efficient.

// Code Explanation
const ctx = app.currentContext;

Previous Problem:

// Code Explanation
// Koa v2 Way
app.use(async (ctx, next) => {
  // Only accessible here
  // If calling other functions, ctx must be passed manually
  someFunction(ctx);
  await next();
});
function someFunction(ctx) {
  // Must obtain ctx through parameters
}

New Way in Koa 3.0:

// Code Explanation
app.use(async (ctx, next) => {
  await next();
});
function someFunction() {
  const ctx = app.currentContext; // Anywhere, directly obtain the ctx of the current request
}

More Standard Parameter Parsing, Fully Adopting URLSearchParams

Koa 3.0 has replaced the native querystring with WHATWG's URLSearchParams, making the parameter parsing behavior consistent with the browser side.

API Detail Optimization, Better Development Experience

  • The call signature of ctx.throw has been adjusted, making exception handling clearer.
  • .redirect('back') has been removed, and .back(fallback_url) has been added, making the redirect logic safer.
  • The return logic of req.origin has been optimized, and source recognition is more accurate in the CORS scenario.
  • Special handling of ENOENT errors has been removed, and developers need to handle errors in streams themselves, enhancing flexibility and consistency.

Dependencies, Improving Security and Compatibility

Core dependency libraries such as type - is, http - errors, cookies, statuses, and supertest have all been upgraded to fix known vulnerabilities and ensure project security.