09/17/24

Fastify v5 breaking changes: should you upgrade?

Spoiler alert: probably not.

3 Min Read

Fastify, one of the most popular web frameworks for Node, just announced a major new release, version 5.0.

We were initially very excited to see if any cool new features or improvements were added, in case there was something we could take inspiration from in Encore.ts.

Unfortunately, after taking it for a spin, we felt it was quite underwhelming: the new release is extremely light on new features, but extremely heavy on breaking changes.

Let's take a look at what's new, and whether it's worth upgrading.

Fastify v5 comes with lots of breaking changes

Don't believe me? Check out the migration guide. It clocks in at almost 2000 words! It lists no less than 20 breaking changes. That's a lot of breakage to consider.

As far as we can tell, most of the breaking changes amount to "cleaning things up" in the code base.

It removes a lot of convenient shorthands for defining JSON Schemas, making schema validation more verbose and less readable.

It also removes a lot of deprecated functionality. Sometimes this is a good thing, if the functionality carries a significant maintenance burden. But in this case, a lot of the removed functionality is essentially a one-liner.

For example, reply.getResponseTime() is removed in favor of reply.elapsedTime. Maybe elapsedTime is a better name, but the cost of maintaining getResponseTime, with its one-line implementation, is zero.

Still, it's easy enough to grep a codebase for getResponseTime and fix it. Other breaking changes are more difficult.

Consider for example fastify.hasRoute() still exists, with exactly the same signature, but the behavior has changed in a subtle way. It used to support passing in a request path to evaluate whether an incoming request matches a route or not. In Fastify v5 the method instead only supports matching the exact string given when registering the route. Migrating over to this is much more difficult, as it's not always clear whether you need to change your code or not.

Fastify v5 has very few, minor improvements

At this point I hear you say, "surely all the breaking changes were done for good reason!". Unfortunately the documentation is surprisingly sparse when it comes to the benefits of upgrading to v5.

The only new feature listed is support for the Diagnostic Channel API. Is that worth upgrading for? For most people, probably not.

The other improvement is a modest performance boost.

From our benchmarking, Fastify v5 is about 5-10% faster than v4, depending on configuration settings and whether you use schema validation. That's nothing to sneeze at! But it's not a game changer either.

Is upgrading worth the hassle? Probably not.

It's disappointing to see a major new release of a popular framework that is so light on new features, and so heavy on breaking changes. Particularly when the breaking changes are seemingly done to clean up internals rather than improving the user experience.

Our belief is that migrating from Fastify v4 to Fastify v5 is probably not worth it for most people.

If you care about performance or reliability, you should probably check out Encore.ts instead of spending time migrating to Fastify v5. It's about twice as fast, and provides a lot of other benefits as well, like TypeScript-native schema validation, automatic tracing (no need to manually instrument your code with the Diagnostic Channel API!), and more.

Requests/sec

Without validation
With schema validation
121,005
107,018
Encore
v1.38.7
65,977
53,136
Fastify v5 (+ Ajv)
v5.0.0 / v8.17.1
62,207
48,397
Fastify v4 (+ Ajv)
v4.27.0 / v8.16.0

What's more, Encore.ts takes backwards compatibility extremely seriously, and follows the Linux Kernel model when it comes to breaking changes: don't. And Encore.ts is of course also open source.

Encore

This blog is presented by Encore, the development platform for building robust type-safe distributed systems with declarative infrastructure.

Like this article?
Get future ones straight to your mailbox.

You can unsubscribe at any time.