---
source_url: https://www.pubnub.com/docs/sdks/javascript/migration-guides/javascript-v12-migration-guide
title: JavaScript SDK 12.0.0 migration guide
updated_at: 2026-06-22T06:37:59.767Z
sdk_name: PubNub JavaScript SDK
sdk_version: 12.0.0
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# JavaScript SDK 12.0.0 migration guide

PubNub JavaScript SDK, use the latest version: 12.0.0

Install:

```bash
npm install pubnub@12.0.0
```

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:

| Area | JavaScript SDK `11.x.x` | JavaScript 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:

```bash
node --version
```

To upgrade using nvm:

```bash
nvm install 22
nvm use 22
```

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

The Node.js transport now uses [undici](https://undici.nodejs.org/) 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.

#### Before (v11.x.x)

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

#### After (v12.0.0)

```javascript
// Proxy must be set explicitly after constructing the client
const pubnub = new PubNub({
  subscribeKey: 'mySubscribeKey',
  publishKey: 'myPublishKey',
  userId: 'myUserId',
});

pubnub.setProxy({
  hostname: 'proxy.example.com',
  port: 8080,
  protocol: 'http',
});
```

## 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:

```bash
npm install react-native-url-polyfill
```

After installing, follow the [react-native-url-polyfill setup instructions](https://github.com/charpeni/react-native-url-polyfill#usage) 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.