From 64caf884b0022353c1577c58436f513abfa6f433 Mon Sep 17 00:00:00 2001 From: Richard Lau Date: Fri, 24 Oct 2025 17:34:38 +0100 Subject: [PATCH 1/2] blog: add Migrating from Node.js 22 to Node.js 24 Summarize breaking and important changes when migrating from Node.js 22 LTS to Node.js 24 LTS. --- .../pages/en/blog/announcements/v22-to-v24.md | 212 ++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 apps/site/pages/en/blog/announcements/v22-to-v24.md diff --git a/apps/site/pages/en/blog/announcements/v22-to-v24.md b/apps/site/pages/en/blog/announcements/v22-to-v24.md new file mode 100644 index 0000000000000..2985aef139bce --- /dev/null +++ b/apps/site/pages/en/blog/announcements/v22-to-v24.md @@ -0,0 +1,212 @@ +--- +date: '2025-10-28T00:00:00.000Z' +category: announcements +title: 'Migrating from Node.js 22 LTS to Node.js 24 LTS' +layout: blog-post +author: The Node.js Project +--- + +With the release of [Node.js 24.11.0][], the Node.js 24 release line has entered Long-Term Support (LTS) and will continue to receive updates through to the end of April 2028. + +If you are migrating from Node.js 22 LTS, this article summarizes the breaking changes that came in [Node.js 23.0.0][] and [Node.js 24.0.0][]. + +## Platform support + +Node.js no longer provides [pre-built binaries][] for: + +- 32-bit Windows (x86) as of Node.js 23.0.0. +- 32-bit Linux on armv7 as of Node.js 24.0.0. + +Pre-built binaries for macOS now require a minimum of macOS 13.5. + +Pre-built binaries for Linux on arm64, ppc64le, s390x and x64 continue to be compatible with glibc 2.28 and above (no change from Node.js 22). + +Please refer to [additional notes if you are building Node.js from source](#building-nodejs-from-source). + +## Assistance with updating source-code + +For some breaking changes, and adoption of some new features, [Node.js provided migrations][userland migrations] are available to aid source-code modifications. + +## Breaking changes + +### Deprecated APIs + +#### Removed APIs + +- [`Cipher` and `Decipher`][DEP0106] classes from `node:crypto`. +- [`dirent.path`][DEP0178]. +- [`fs.truncate()` using a file descriptor][DEP0081]. +- [`OutgoingMessage.prototype._headers`, `OutgoingMessage.prototype._headerNames`][DEP0066] from the `node:http` module. +- [HTTP/2 priority signaling][DEP0194]. +- [`net._setSimultaneousAccepts()`][DEP0121]. +- [`process.assert()`][DEP0100]. +- [`timers.active()`][DEP0126]. +- [`timers.enroll()`][DEP0095]. +- [`timers.unenroll()`][DEP0096]. +- [`timers._unrefActive()`][DEP0127]. +- [`tls.createSecurePair()`][DEP0064]. +- [`tls.SecurePair`][DEP0043]. +- [`tls` `Server.prototype.setOptions()`][DEP0122]. +- [`util.isBoolean()`][DEP0045]. +- [`util.isBuffer()`][DEP0046]. +- [`util.isDate()`][DEP0047]. +- [`util.isError()`][DEP0048]. +- [`util.isFunction()`][DEP0049]. +- [`util.isNull()`][DEP0050]. +- [`util.isNullOrUndefined()`][DEP0051]. +- [`util.isNumber()`][DEP0052]. +- [`util.isObject()`][DEP0053]. +- [`util.isPrimitive()`][DEP0054]. +- [`util.isRegExp()`][DEP0055]. +- [`util.isString()`][DEP0056]. +- [`util.isSymbol()`][DEP0057]. +- [`util.isUndefined()`][DEP0058]. +- [`util.log()`][DEP0059]. +- [`util._extend()`][DEP0060]. +- [`zlib.bytesRead`][DEP0108]. +- Internal process bindings for `async_wrap`, `crypto`, `http_parser`, `signal_wrap`, `url`, and `v8`. + +#### Removed command-line options + +- [`--trace-atomics-wait`][DEP0165]. + +The following command-line options have been removed as they referred to features that are no longer experimental: + +- `--no-experimental-global-customevent`. +- `--no-experimental-fetch`. +- `--no-experimental-global-webcrypto`. + +#### New runtime deprecations + +Runtime deprecations result in warnings being printed to the console when first used. + +- [`SlowBuffer`][DEP0030] class. +- [`crypto.fips`][DEP0093]. +- [`fs.existsSync` with invalid argument types][DEP0187]. +- [`fs.F_OK`, `fs.R_OK`, `fs.W_OK`, `fs.X_OK`][DEP0176]. +- [Instantiating `node:repl` classes without `new`][DEP0185]. +- [Instantiating `node:zlib` classes without `new`][DEP0184]. +- [Passing `args` to `node:child_process` `execFile`/`spawn` with `shell` option `true`][DEP0190]. +- [Short GCM authentication tags without explicit `authTagLength`][DEP0182]. +- [`url.parse()`][DEP0169]. + +### OpenSSL 3.5 + +Pre-built binaries of Node.js 24 LTS, or builds using the default build configuration options, include OpenSSL 3.5. While Node.js 22 LTS got OpenSSL 3.5 in [Node.js 22.20.0][], the default [security level][openssl-security-level] was lowered there to match the [default security level in OpenSSL 3.0 of `1`][openssl30seclevel] to minimize disruption when updating within the Node.js 22 release line. Node.js 24 LTS uses the [default security level from OpenSSL 3.5 of `2`][openssl35seclevel], which means that: + +- RSA, DSA and DH keys shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. +- Any cipher suite using RC4 is also prohibited. + +### Other changes of behavior + +- Stricter `fetch()` compliance, including removal of support for third party `Blob`, `FormData`, and `AbortController` [#56070](https://github.com/nodejs/node/pull/56070). +- Stricter validation of `AbortSignal` [#54965](https://github.com/nodejs/node/pull/54965). +- [`CloseEvent`][CloseEvent], `Float16Array` and [`URLPattern`][URLPattern] have now been added to the [Global object][]. +- Attempting to pipe to a closed or destroyed stream will now result in a `ERR_STREAM_UNABLE_TO_PIPE` error [#53241](https://github.com/nodejs/node/pull/53241). +- The ESM CommonJS wrapper now exports 'module.exports' [#53848](https://github.com/nodejs/node/pull/53848). +- `buffer.File` is now cloneable [#47613](https://github.com/nodejs/node/pull/47613). +- New requests on existing HTTP/2 connections will not be able to do so once server close is initiated [#57586](https://github.com/nodejs/node/pull/57586). +- Streams now catch and forward errors from `dest.write()` [#55270](https://github.com/nodejs/node/pull/55270). +- `readline` no longer ignores unicode line separators [#57591](https://github.com/nodejs/node/pull/57591). +- Calling `readline.pause()`, `readline.resume()` or `readline.write()` on a closed `readline` interface now results in a `ERR_USE_AFTER_CLOSE` error [#57680](https://github.com/nodejs/node/pull/57680) +- The `ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED` error has been corrected to `ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED` [#52627](https://github.com/nodejs/node/pull/52627). +- `EventEmitterAsyncResource` fields are now private [#54889](https://github.com/nodejs/node/pull/54889). +- Async context frame added to `AsyncResource` [#56082](https://github.com/nodejs/node/pull/56082). +- `AsyncLocalStorage` now defaults to `AsyncContextFrame` [#55552](https://github.com/nodejs/node/pull/55552). + +#### Argument/option validation + +The following API's have changed how arguments/options are validated: + +- Buffer API's now throw when writing beyond the end of the buffer [#54588](https://github.com/nodejs/node/pull/54588). +- when writing a string to a buffer, or calling `buffer.toString()` on a large buffer, `buflen` is now capped within integer range [#51821](https://github.com/nodejs/node/pull/51821). +- `fs.symlink()` no longer allows non-string values for the `type` option [#49741](https://github.com/nodejs/node/pull/49741). +- `timers.clearImmediate` for the `immediate` argument [#57069](https://github.com/nodejs/node/pull/57069). +- Timers now emit a warning if delay is negative or `NaN` [#46678](https://github.com/nodejs/node/pull/46678). +- `server.listen()` host name validation [#54470](https://github.com/nodejs/node/pull/54470). +- Long path names for pipes no longer truncate the pathname and instead throw an error [#52347](https://github.com/nodejs/node/pull/52347). +- string_decoder encoding validation [#54957](https://github.com/nodejs/node/pull/54957). +- `ERR_CRYPTO_SCRYPT_INVALID_PARAMETER` has been removed [#53305](https://github.com/nodejs/node/pull/53305). + +#### Path handling + +- Path handling on Windows with trailing slashes in `fs` API's is now consistent with other platforms [#54160](https://github.com/nodejs/node/pull/54160). +- Bugs and inconsistencies in `path` handling [#54224](https://github.com/nodejs/node/pull/54224). + +#### Test runner + +- `WeakMap` and `WeakSet` comparison handling in `assert` and `util` API's has been changed [#53495](https://github.com/nodejs/node/pull/53495). +- Detect only tests when `--test` is not used [#54881](https://github.com/nodejs/node/pull/54881). +- The test runner now defaults to the `spec` reporter. TAP output is still available via the `--test-reporter=tap` CLI flag. [#54548](https://github.com/nodejs/node/pull/54548). +- The `lcov` reporter is now exposed as a newable function to allow `options` to be set on it [#52403](https://github.com/nodejs/node/pull/52403). + +### C/C++ addons + +[Addons][] linking against V8 APIs may need to be updated for V8 13.6. This includes C++20 support needing to be enabled (previously C++17). Where possible, the project recommends using [NODE-API][] to avoid needing to recompile for new versions of V8. + +### Building Node.js from source + +If you are building Node.js from source, you may need to update your compiler toolchain. + +- For AIX and Linux platforms, the minimum supported version of [gcc][] is 12.2. +- For macOS the minimum supported version of [Xcode][] is 16.1. + +Node.js' `configure` script will warn if you attempt to build Node.js with a compiler toolchain that does not meet the minimum supported version but will not actively prevent you from trying. + +[Addons]: https://nodejs.org/docs/latest-v24.x/api/addons.html +[CloseEvent]: https://nodejs.org/docs/latest-v24.x/api/globals.html#class-closeevent +[DEP0043]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0043 +[DEP0045]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0045 +[DEP0046]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0046 +[DEP0047]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0047 +[DEP0048]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0048 +[DEP0049]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0049 +[DEP0050]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0050 +[DEP0051]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0051 +[DEP0052]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0052 +[DEP0053]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0053 +[DEP0054]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0054 +[DEP0055]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0055 +[DEP0056]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0056 +[DEP0057]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0057 +[DEP0058]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0058 +[DEP0059]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0059 +[DEP0060]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0060 +[DEP0064]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0064 +[DEP0066]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0066 +[DEP0030]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0030 +[DEP0081]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0081 +[DEP0093]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0093 +[DEP0095]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0095 +[DEP0096]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0096 +[DEP0100]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0100 +[DEP0106]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0106 +[DEP0108]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0108 +[DEP0121]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0121 +[DEP0122]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0122 +[DEP0126]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0126 +[DEP0127]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0127 +[DEP0165]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0165 +[DEP0169]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0169 +[DEP0176]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0176 +[DEP0178]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0178 +[DEP0182]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0182 +[DEP0184]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0184 +[DEP0185]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0185 +[DEP0187]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0187 +[DEP0190]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0190 +[DEP0194]: https://nodejs.org/docs/latest-v24.x/api/deprecations.html#DEP0194 +[gcc]: https://gcc.gnu.org/ +[Global object]: https://nodejs.org/docs/latest-v24.x/api/globals.html +[NODE-API]: https://nodejs.org/docs/latest-v24.x/api/addons.html#node-api +[Node.js 22.20.0]: https://nodejs.org/blog/release/v22.20.0 +[Node.js 23.0.0]: https://nodejs.org/blog/release/v23.0.0 +[Node.js 24.0.0]: https://nodejs.org/blog/release/v24.0.0 +[Node.js 24.11.0]: https://nodejs.org/blog/release/v24.11.0 +[openssl30seclevel]: https://docs.openssl.org/3.0/man3/SSL_CTX_set_security_level/ +[openssl35seclevel]: https://docs.openssl.org/3.5/man3/SSL_CTX_set_security_level/ +[openssl-security-level]: https://nodejs.org/docs/latest-v24.x/api/tls.html#openssl-security-level +[pre-built binaries]: https://nodejs.org/en/download +[userland migrations]: https://nodejs.org/en/learn/migrations/introduction +[URLPattern]: https://nodejs.org/docs/latest-v24.x/api/globals.html#class-urlpattern +[Xcode]: https://developer.apple.com/xcode/ From cd57456e31ec1cdbf74f355fadf80a3beac835f1 Mon Sep 17 00:00:00 2001 From: Richard Lau Date: Mon, 27 Oct 2025 16:36:21 +0000 Subject: [PATCH 2/2] fixup! blog: add Migrating from Node.js 22 to Node.js 24 Co-authored-by: Brian Muenzenmeyer Signed-off-by: Richard Lau --- apps/site/pages/en/blog/announcements/v22-to-v24.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/site/pages/en/blog/announcements/v22-to-v24.md b/apps/site/pages/en/blog/announcements/v22-to-v24.md index 2985aef139bce..567c4a414f931 100644 --- a/apps/site/pages/en/blog/announcements/v22-to-v24.md +++ b/apps/site/pages/en/blog/announcements/v22-to-v24.md @@ -109,7 +109,7 @@ Pre-built binaries of Node.js 24 LTS, or builds using the default build configur - Streams now catch and forward errors from `dest.write()` [#55270](https://github.com/nodejs/node/pull/55270). - `readline` no longer ignores unicode line separators [#57591](https://github.com/nodejs/node/pull/57591). - Calling `readline.pause()`, `readline.resume()` or `readline.write()` on a closed `readline` interface now results in a `ERR_USE_AFTER_CLOSE` error [#57680](https://github.com/nodejs/node/pull/57680) -- The `ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED` error has been corrected to `ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED` [#52627](https://github.com/nodejs/node/pull/52627). +- The `ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED` error has been corrected to `ERR_TLS_PSK_SET_IDENTITY_HINT_FAILED` [#52627](https://github.com/nodejs/node/pull/52627). - `EventEmitterAsyncResource` fields are now private [#54889](https://github.com/nodejs/node/pull/54889). - Async context frame added to `AsyncResource` [#56082](https://github.com/nodejs/node/pull/56082). - `AsyncLocalStorage` now defaults to `AsyncContextFrame` [#55552](https://github.com/nodejs/node/pull/55552).