Fastify v5 Update: Node.js 20 Requirements and Key Changes
Fastify has officially released its fifth major version, v5. As a popular web framework in the Node.js ecosystem known for high throughput and a lightweight architecture, it is worth examining how this major update impacts existing code.
Fastify v5 has boldly shed legacy runtime compatibility and streamlined the framework, focusing on standard diagnostic tools in modern Node.js environments and full schema definitions.
Higher Minimum Runtime Spec: Node.js 20 or Higher Required
The most significant change in Fastify v5 is the minimum environment requirement. It has completely dropped support for Node.js 18, making Node.js 20 or higher mandatory. As v4's long-term support phase concludes, this decision was made to actively leverage the latest runtime performance improvements and built-in diagnostic tools.
Before upgrading your project to Fastify v5, ensure your server environment or container base image is running Node.js 20 or later. Attempting to run it on older Node.js versions will result in engine compatibility warnings or failures during installation or execution.
Removal of jsonShorthand and Stricter JSON Schema
Support for jsonShorthand, the non-standard shorthand notation for route validation, has been completely removed. In Fastify v4, omitting the top-level type: 'object' was permitted when declaring query or body schemas. Starting with v5, only complete JSON Schema objects that strictly follow the schema specification are accepted.
According to the official Fastify v5 documentation, you must now explicitly state the top-level type for schemas as shown below.
If any shorthand schemas remain in your existing project, a compilation error will occur during Fastify instance initialization, so you should audit the schema structures across your route definitions.
Integration with node:diagnostics_channel and Improved Observability
For application monitoring, integration with the built-in Node.js diagnostic channel, node:diagnostics\_channel, is now officially supported. You can subscribe to the entire lifecycle—such as HTTP request reception, routing, and response completion—as standard diagnostic events without needing separate third-party plugins or monkey-patching.
This allows for precise measurements with lower overhead when building OpenTelemetry integration libraries or distributed tracing systems.
Response Time Measurement and Network Property Cleanup
Some frequently used helper methods and properties have also been standardized. The reply.getResponseTime() method, which previously returned the response time in milliseconds, has been removed and replaced by the reply.elapsedTime getter property.
Access to request.connection, a relic of the old Node.js HTTP object, has also been removed. If socket information is needed, you must directly reference request.socket or request.raw.socket. To increase consistency with the internal router 'find-my-way', the path matching rules for fastify.hasRoute() have been unified to match the router's actual behavior.
Adoption and Getting Started
If you are preparing a new Node.js service, starting with Fastify v5 on Node.js 20 or the latest LTS environment is the natural path. Because the base structure is now stricter, it's a great opportunity to apply standard JSON Schema from the design phase to ensure type safety.
When migrating an existing Fastify v4 project, simply confirming these two things in order is sufficient: verify the server is updated to Node.js 20, and search for/update any remaining shorthand schemas and reply.getResponseTime() calls in your route definitions.
