blog: add Migrating from Node.js 22 to Node.js 24

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/