Fixed

• Fixed Windows source builds against Node.js 26 failing with LINK : fatal error LNK1117: syntax error in option 'opt:lldltojobs=2'. Node 26 was built with clang-cl + lld + ThinLTO (PR nodejs/node#63114, released in v26.3.0), and node-gyp's create-config-gypi.js seeds the addon's config.gypi from process.config of the running Node binary — picking up enable_thin_lto: true and lto_jobs: <n> from how Node itself was built. Node's installed common.gypi then unconditionally appends -flto=thin to MSVC cl.exe's AdditionalOptions and /opt:lldltojobs=<n> to link.exe's. MSVC ignores -flto=thin (warning) but rejects /opt:lldltojobs=<n> because /OPT: only accepts REF/ICF/NOREF/NOICF/LBR/NOLBR. Force them off via npm_config_enable_thin_lto=false + npm_config_enable_lto=false in the Windows build script, which node-gyp forwards as -Denable_thin_lto=false gyp defines (top precedence — binding.gyp variables don't override config.gypi's, they're a separate gyp scope).

Fixed

• Fixed Windows source builds linking against libidn2 (and its libunistring transitive dep) instead of using the Windows-native WinIDN backed by Normaliz.lib. The vcpkg manifest was requesting both the idn and idn2 curl features, which forced vcpkg's curl port to pull libidn2 in; only idn is needed and lets the port pick WinIDN on Windows. Smaller binary, fewer transitive deps.
• Fixed Windows source builds failing in deeply-nested consumer paths (typical of pnpm v10 monorepos) with CreateProcessW failed with 206 (The filename or extension is too long). vcpkg's bundled pwsh.exe sits at vcpkg/downloads/tools/powershell-core-<ver>-windows/pwsh.exe — easy to push past Windows' MAX_PATH from inside a deep node_modules/.pnpm/ tree. vcpkg's clone now goes to %LOCALAPPDATA%\node-libcurl-vcpkg\<moduleRootHash>\ regardless of where the package lives, so the toolchain's internal paths stay short.
• Fixed Windows source builds failing with pkg-config: 'libcrypto'/'zlib' not found while building libssh2 in nested consumer paths. vcpkg_installed was also being written inside the deep module root, and msys2 pkg-config's PKG_CONFIG_PATH parsing tripped over both the path length and the drive-letter colon. vcpkg_installed now goes to %LOCALAPPDATA%\node-libcurl-vcpkg\<hash>-installed via --x-install-root, and vcpkg-get-info.js resolves against that path so binding.gyp still finds the libs.
• Fixed vcpkg.exe's git clone failing with Filename too long while writing pack .keep files on deep paths. The clone now passes git -c core.longpaths=true.
• Propagate VCPKG_DISABLE_METRICS=1 to all vcpkg subprocess invocations from scripts/vcpkg-setup.js (it was being set in the env action but lost when the install script spawned vcpkg.exe).

Changed

• A consumer install of node-libcurl under pnpm v10 now requires opting node-libcurl's lifecycle scripts in via pnpm.onlyBuiltDependencies: ["node-libcurl"] in the consumer's package.json (or pnpm add --allow-build=node-libcurl). pnpm v10's default scripts-off policy otherwise leaves the package installed but non-functional — no vcpkg setup, no native addon build. This isn't a node-libcurl change per se, but is now exercised by the new windows-consumer-install CI workflow so the regression-protected path is documented.

Fixed

• Fixed Curl.perform() intermittently throwing CurlMultiError: Could not remove easy handle from multi handle.: API function called from within callback (CURLM_RECURSIVE_API_CALL) under concurrent load, particularly visible on Alpine. The regression came from v5.0.0 enabling libcurl 8.17's new CURLMOPT_NOTIFYFUNCTION API, which fires from inside curl_multi_socket_action. The notification resolved the perform-promise synchronously, and the resulting .then() microtask called curl_multi_remove_handle while libcurl was still on its own call stack. The removal is now deferred via setImmediate so libcurl can unwind first. (fixes #439)
• Fixed macOS x64 prebuilt binary tarballs containing an arm64 binary instead of x86_64. The universal build packaging in scripts/ci/build.sh was extracting both architectures to the same output file before either was packaged, so the second lipo extraction overwrote the first. This affected all macOS releases since v5.0.0. (#446, fixes #445)
• Fixed CurlMimePart#setDataStream hanging on Linux when libcurl needed a second read callback after the stream emitted its initial data. The mime read callback wasn't tracking CURLPAUSE_SEND state after returning CURL_READFUNC_PAUSE, so isPausedSend stayed false and the test/example unpause callbacks were silent no-ops. The unpause is now also deferred via setImmediate to avoid re-entering libcurl while it's still processing the pause. (#448)
• Fixed vcpkg build failures when the exact OpenSSL version bundled with Node.js isn't present in the vcpkg registry. The build now resolves to the closest compatible version (preferring a newer patch on the same minor line, falling back to the closest lower patch, then the next minor) with a clear warning about the substitution. (#447)
• Fixed Alpine CI builds failing with fatal error: ngtcp2/ngtcp2_crypto_quictls.h: No such file or directory after the ngtcp2 1.17.0 + OpenSSL 3.5+ combination switched to the new libngtcp2_crypto_ossl backend. Added the statically-built OpenSSL's pkgconfig dir to PKG_CONFIG_PATH so libcurl's probe for libngtcp2_crypto_ossl can resolve its Requires: libcrypto on systems without system OpenSSL.
• Fixed Windows CI builds failing with Could not find any Visual Studio installation to use after GitHub started serving Visual Studio 2026 (v145) on the windows-2025 runner ahead of the official 2026-06-15 migration. The build script no longer pins msvs_version=2022, letting node-gyp 12.1.0+ auto-detect whichever supported MSVC toolset is installed.

Added

• Node.js 26 to the CI matrix. Prebuilt binaries are now published for Node 26 alongside the existing 22, 24, and 25 versions.

Changed

• Bumped node-gyp from 11.4.2 to 12.3.0 and @mapbox/node-pre-gyp from 2.0.0 to 2.0.3. node-gyp v12.1.0+ adds Visual Studio 2026 detection support. The only node-gyp v12 breaking change (engine range bumped to ^20.17.0 || >=22.9.0) does not affect this project, which already requires Node.js ≥ 22.20.0.
• Bumped Alpine container image from alpine3.21 to alpine3.22 so the Node.js 26 image variant is available (node:26-alpine3.21 is not published). Musl is 1.2.5 across Alpine 3.20–3.23, so the prebuilt binary remains runtime-compatible on Alpine 3.21.
• The unpause callback documentation and examples for CurlMimePart#setDataStream and Easy#setMimePost now correctly reference CurlPause.Send instead of CurlPause.Recv. Mime upload data is supplied via the read callback, so pausing affects CURLPAUSE_SEND. (#448)

Fixed

• Fixed the types on the FileInfo object. With 5.0.0, the properties were changed to be all in lowercase, to follow the libcurl struct more closely.

Fixed

• Building from source on macOS would not work properly.

Breaking Change

• The prebuilt binary is now built with libcurl 8.17.0. Every breaking change introduced by libcurl 8 is also a breaking change for this version.

  Version: libcurl/8.17.0 OpenSSL/3.5.2 zlib/1.3.1 brotli/1.1.0 zstd/1.5.7 libidn2/2.1.1 libssh2/1.10.0 nghttp2/1.66.0 ngtcp2/1.17.0 nghttp3/1.12.0 OpenLDAP/2.6.9
  Protocols: dict, file, ftp, ftps, gopher, gophers, http, https, imap, imaps, ldap, ldaps, mqtt, pop3, pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp, ws, wss
  Features: AsynchDNS, IDN, IPv6, Largefile, NTLM, SSL, libz, brotli, TLS-SRP, HTTP2, UnixSockets, HTTPS-proxy, alt-svc
  

• Minimum supported Electron version is now Electron v38.0.0 (moving forward prebuilt binaries will only be available for the latest 2 versions of Electron).
• Mininum supported libcurl version is now libcurl 7.81.0.
• Windows 32-bit support is now dropped.
• Minimum supported versions:
  • Node.js >= v22.20.0 (which bundles OpenSSL 3.5.2).
  • Electron >= v38.0.0.
  • libcurl >= v7.81.0.
  • Ubuntu >= v22.04.
  • Alpine >= 3.21
  • C++ compilers supporting c++20
• The FileInfo object properties are now all in lowercase, to follow the libcurl struct more closely.
• Errors thrown by the addon are now instances of one of the following classes:
  • CurlEasyError
  • CurlMultiError
  • CurlSharedError
    These classes extends the CurlError class. Previously the addon used to throw only native Javascript errors, such as Error, TypeError, etc.
    The curly related errors also inherit from the CurlError class, and do not have a isCurlError property anymore.
    Any caught error thrown from user callbacks will be added as the cause property of the error.
• Every Easy handle is now initialized with default CA certificates from Node.js's tls module, by using the result of the getCACertificates function. This is done using CURLOPT_CAINFO_BLOB. This is a breaking change if you were passing custom CA certificates before using CAINFO, as CURLOPT_CAINFO_BLOB takes priority over it. If that is the case, you can avoid the default behavior by calling setOpt("CAINFO_BLOB", null) on the Easy handle. The TLS certificate is loaded into memory only once for each JavaScript context.
• HSTSREADFUNCTION callback now receives an object with the maxHostLengthBytes property, which is the maximum length of the host name that can be returned by the callback.
• The minimum macOS version is now Sonoma (13)
• Curl.globalCleanup is a no-op now. The addon will automatically call curl_global_cleanup when the process exits. This method will be removed in a future major version.
• Curl.globalInit is a no-op now. The addon will automatically call curl_global_init when the process starts. This method will be removed in a future major version.

Fixed

• CurlHttpVersion.V3 not being set to the proper value (was not set to 30)

Added

• Prebuilt binaries have HTTP/3 support enabled across all platforms. This is supported by licurl when building with OpenSSL >= 3.5 and nghttp3 >= 1.66. To use OpenSSL >= 3.5 a Node.js version >= 22.20.0 is required.
• The addon has been rewritten to use N-API, which will streamline the process of supporting newer Node.js versions in the future.
• The addon is now worker threads safe. See examples/22-worker-threads.js for usage example.
• Added native WebSocket support (requires libcurl >= 7.86.0):
  • Easy.wsRecv(buffer) - Receive WebSocket frames with metadata
  • Easy.wsSend(buffer, flags, fragsize?) - Send WebSocket frames (text, binary, ping, pong, close)
  • Easy.wsMeta() - Get WebSocket frame metadata
  • CurlWs enum for WebSocket frame flags (Text, Binary, Close, Ping, Pong, Cont, Offset)
  • CurlWsOptions enum for WebSocket options (RawMode, NoAutoPong)
  • CurlWsFrame interface for frame metadata (age, flags, offset, bytesleft, len)
  • Support for CONNECT_ONLY mode with value 2 for WebSocket connections
  • See examples/21-websockets-native.js for usage example
• Added MIME API support for multipart form data (replaces deprecated HTTPPOST):
  • CurlMime class for creating multipart MIME structures
  • CurlMimePart class for individual MIME parts
  • CurlMimeOpt enum for MIME options (FormEscape)
  • Added CURLOPT_MIME_OPTIONS and CURLOPT_MIMEPOST options
  • Easy.setMimePost(mime), Curl.setMimePost(mime), and curlyMimePost alternatives for setting MIME data in a structured way.
  • See examples/23-mime-post-easy.js for usage example
• Added SSH host key verification support (requires libcurl >= 7.84.0):
  • CURLOPT_SSH_HOSTKEYFUNCTION callback for custom host key verification
  • CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 option for SHA256 fingerprint verification
  • CurlSshKeyType enum for SSH host key types (Unknown, Rsa, Dss, Ecdsa, Ed25519)
  • CurlSshKeyMatch enum for SSH host key verification results (Ok, Mismatch)
• Added HTTP/2 stream priority support:
  • CURLOPT_STREAM_DEPENDS - Set stream dependency
  • CURLOPT_STREAM_DEPENDS_E - Set stream dependency (exclusive)
  • CURLOPT_STREAM_WEIGHT - Set stream weight for resource allocation
• Added CURLOPT_INTERLEAVEFUNCTION callback for handling RTSP interleaved data
• Added new Multi.perform method for adding Easy instances to a Multi instance. This will eventually replace the Multi.addHandle and Multi.onMessage methods, which are now deprecated.
• Added the following new enums:
  • CurlFollow
  • CurlMultiNetworkChanged
  • CurlWs
  • CurlWsOptions
• Added following enum members:
  • CurlWriteFunc.Abort
  • CurlShareLock.DataShare
  • CurlHttpVersion.V3Only
  • CurlProxy.Https2
  • CurlCode.CURLE_UNRECOVERABLE_POLL
  • CurlCode.CURLE_TOO_LARGE
  • CurlCode.CURLE_ECH_REQUIRED
  • CurlSslOpt.Earlydata
• Added support for the following extra easy options:
  • https://curl.se/libcurl/c/CURLOPT_CA_CACHE_TIMEOUT.html
  • https://curl.se/libcurl/c/CURLOPT_MAIL_RCPT_ALLOWFAILS.html
  • https://curl.se/libcurl/c/CURLOPT_HAPROXY_CLIENT_IP.html
  • https://curl.se/libcurl/c/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.html
  • https://curl.se/libcurl/c/CURLOPT_ECH.html
  • https://curl.se/libcurl/c/CURLOPT_TCP_KEEPCNT.html
  • https://curl.se/libcurl/c/CURLOPT_UPLOAD_FLAGS.html
  • https://curl.se/libcurl/c/CURLOPT_SSL_SIGNATURE_ALGORITHMS.html
• Added following info options:
  • https://curl.se/libcurl/c/CURLINFO_CONN_ID.html
  • https://curl.se/libcurl/c/CURLINFO_XFER_ID.html
  • https://curl.se/libcurl/c/CURLINFO_QUEUE_TIME_T.html
  • https://curl.se/libcurl/c/CURLINFO_USED_PROXY.html
  • https://curl.se/libcurl/c/CURLINFO_POSTTRANSFER_TIME_T.html
  • https://curl.se/libcurl/c/CURLINFO_EARLYDATA_SENT_T.html
  • https://curl.se/libcurl/c/CURLINFO_PROXYAUTH_USED.html
  • https://curl.se/libcurl/c/CURLINFO_HTTPAUTH_USED.html
• Added the following multi options:
  • https://curl.se/libcurl/c/CURLMOPT_NETWORK_CHANGED.html
• Added Curl.id, Easy.id, Multi.id, and Share.id properties, which return the unique ID of each instance. The value is unique across threads.
• There are build attestations for the prebuilt binaries now, which can be used to verify the authenticity of the binaries.

v4.1.0...v5.0.0-1