JavaScript SDK 11.0.0 migration guide

The 11.0.0 release of the JavaScript SDK changes the default values of enableEventEngine and restore, and removes the enforced upper bounds on user-provided maximumRetry and maximumDelay values in retry policies. These are behavioral breaking changes for applications that omit these options from their configuration. Applications that set them explicitly are unaffected.

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

Differences between 10.x.x and 11.0.0

See the major differences between the versions:

Feature	JavaScript SDK 10.x.x	JavaScript SDK 11.0.0
enableEventEngine default	false	true
restore default	false	true
maximumRetry upper-bound validation	Enforced (10 for linear, 6 for exponential)	Not enforced
maximumDelay upper-bound validation	Enforced (150 s for exponential)	Not enforced

enableEventEngine defaults to true

enableEventEngine now defaults to true. All new PubNub client instances use the new subscription workflow unless you explicitly set it to false.

When enableEventEngine is true:

• The SDK uses the standardized subscribe and presence workflows and emits the updated set of status events.
• maintainPresenceState is automatically enabled, so custom presence state is re-sent on every subscribe call.
• autoNetworkDetection is ignored.

Retry policy default

When enableEventEngine is true (the default in 11.0.0) and no retryConfiguration is supplied, the SDK automatically applies ExponentialRetryPolicy to subscribe operations with minimumDelay: 2, maximumDelay: 150, and maximumRetry: 6. An explicitly set retryConfiguration applies regardless of enableEventEngine.

Messages, presence events, and all other APIs work exactly as before. If your application inspects status categories, see Migrating to the new subscription loop for a full comparison of what has changed.

To keep the legacy subscription manager, set enableEventEngine: false:

Before (v10.x.x)

1const pubnub = new PubNub({
2  subscribeKey: 'mySubscribeKey',
3  publishKey: 'myPublishKey',
4  userId: 'myUserId',
5  // enableEventEngine not set — defaulted to false
6});

After (v11.0.0)

1const pubnub = new PubNub({
2  subscribeKey: 'mySubscribeKey',
3  publishKey: 'myPublishKey',
4  userId: 'myUserId',
5  enableEventEngine: false, // set explicitly to keep legacy behavior
6});

restore defaults to true

restore now defaults to true in browser environments. This requires listenToBrowserNetworkEvents to be true, which is also the default.

When restore is true, the SDK moves the client into the disconnected state on network loss without sending leave events. It preserves the current timetoken and active channel list so the SDK can catch up on missed messages when connectivity is restored.

To restore the pre-v11.0.0 behavior, where the client resets the timetoken and channel list on network loss, set restore: false.

You must then re-subscribe manually after PNNetworkUpCategory fires.

Before (v10.x.x)

1const pubnub = new PubNub({
2  subscribeKey: 'mySubscribeKey',
3  publishKey: 'myPublishKey',
4  userId: 'myUserId',
5  // restore not set — defaulted to false
6});

After (v11.0.0)

1const pubnub = new PubNub({
2  subscribeKey: 'mySubscribeKey',
3  publishKey: 'myPublishKey',
4  userId: 'myUserId',
5  restore: false, // set explicitly to keep legacy behavior
6});

Retry policy validation limits removed

The SDK no longer enforces upper bounds when you call validate() on LinearRetryPolicy or ExponentialRetryPolicy. Values for maximumRetry and maximumDelay that previously caused a validation error are now accepted without restriction.

Existing code is unaffected unless it relied on the validation error to catch misconfigurations. Review your retry configuration to confirm the values are appropriate for your application.

Set retry limits explicitly

The JavaScript SDK doesn't enforce upper bounds on maximumRetry or maximumDelay.

Without limits, misconfigured policies may cause excess network traffic, battery drain, or usage spikes. Always choose values suited to your app.

For more information on configuring retry policies, refer to Reconnection policy and the retryConfiguration parameter reference.

Migration steps

To migrate from JavaScript SDK 10.x.x to 11.0.0:

1. Upgrade the SDK in your project.
2. If your application relies on the legacy subscription manager, set enableEventEngine: false.
3. If your application relies on the legacy network-loss behavior (timetoken and channel list reset), set restore: false.
4. Review any LinearRetryPolicy or ExponentialRetryPolicy configurations to confirm that maximumRetry and maximumDelay values are within acceptable bounds for your use case.
5. If you inspect PNConnectedCategory to detect subscription list changes, update your listener to handle PNSubscriptionChangedCategory instead. See Migrating to the new subscription loop.