On this page

JavaScript SDK 12.0.0 migration guide

The 12.0.0 release of the JavaScript SDK raises the minimum supported Node.js version, replaces the Node.js transport layer, and changes how the React Native URL polyfill is delivered. These are breaking changes for applications that run on Node.js 18 or 20, use SOCKS or PAC-file proxies, or rely on the polyfill being installed automatically in React Native projects.

This guide summarizes the differences and the steps to migrate to JavaScript SDK v12.0.0.

Differences between 11.x.x and 12.0.0​

See the major differences between the versions:

AreaJavaScript SDK 11.x.xJavaScript SDK 12.0.0
Minimum Node.js version
18
22
Node.js transport
node-fetch + proxy-agent
undici
SOCKS proxy support
Yes (via proxy-agent)
No
PAC-file proxy support
Yes (via proxy-agent)
No
Auto-proxy from env vars (HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy, ALL_PROXY, NO_PROXY)
Yes (via proxy-agent)
No
HTTP/HTTPS proxy
Yes
Yes
React Native URL polyfill
Bundled automatically
Must be installed explicitly

Node.js version requirement raised to 22​

Node.js 18.x and 20.x are no longer supported. You must upgrade to Node.js 22 or later before upgrading the SDK.

To check your current Node.js version:

node --version

To upgrade using nvm:

nvm install 22
nvm use 22

Transport layer replaced: node-fetch + proxy-agent replaced by undici​

The Node.js transport now uses undici instead of node-fetch, proxy-agent, and form-data. This change has no user-facing API impact for most applications. The SDK configuration options and method signatures are unchanged.

HTTP and HTTPS proxy support continues to work via undici's ProxyAgent. Pass your proxy URL using the SDK's proxy option as before.

Removed proxy features​

The following proxy capabilities that proxy-agent provided are no longer available in v12.0.0:

  • SOCKS4 and SOCKS5 proxies
  • PAC-file proxies
  • Automatic proxy resolution from environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY)

If your application relied on SOCKS or PAC-file proxies, there is no replacement in v12.0.0. If your application relied on automatic proxy resolution from environment variables, replace that configuration with an explicit HTTP or HTTPS proxy passed via setProxy().

Automatic environment-variable proxy resolution​

In v11.x.x, proxy-agent (via proxy-from-env) automatically routed all SDK traffic through any proxy address set in the environment. This applied to both uppercase and lowercase variants: HTTP_PROXY, HTTPS_PROXY, NO_PROXY, http_proxy, https_proxy, no_proxy, and ALL_PROXY. This automatic resolution no longer happens in v12.0.0. You must call setProxy() on the client with the proxy address explicitly.

1// proxy-agent picked up HTTP_PROXY / http_proxy automatically from the environment
2// No proxy configuration needed in code
3const pubnub = new PubNub({
4  subscribeKey: 'mySubscribeKey',
5  publishKey: 'myPublishKey',
6  userId: 'myUserId',
7});

React Native: react-native-url-polyfill must be installed explicitly​

In v11.x.x, react-native-url-polyfill was a direct dependency of the SDK and was installed automatically when you ran npm install pubnub.

In v12.0.0, it is listed as an optional peer dependency. You must install it manually in your React Native project:

npm install react-native-url-polyfill

After installing, follow the react-native-url-polyfill setup instructions to apply the polyfill in your app entry point. Without this step, React Native apps that depend on the URL global may encounter runtime errors.

Migration steps​

To migrate from JavaScript SDK 11.x.x to 12.0.0:

  1. Upgrade Node.js to version 22 or later. Node.js 18 and 20 are no longer supported.
  2. Upgrade the SDK in your project.
  3. If your application relied on automatic proxy resolution from environment variables (HTTP_PROXY, HTTPS_PROXY, http_proxy, https_proxy, ALL_PROXY, NO_PROXY, or no_proxy), call pubnub.setProxy({ hostname, port, protocol }) explicitly instead. If your application used SOCKS or PAC-file proxies, those proxy types are no longer supported.
  4. If you are building a React Native app, install react-native-url-polyfill explicitly and apply it in your app entry point.
Last updated on
On this page