PubNub JavaScript and TypeScript SDK

PubNub provides global infrastructure for real-time, interactive applications.

Publish and receive messages in JavaScript and TypeScript. Use this SDK for browsers, Node.js, React, React Native, Angular, Vue, and other JavaScript or TypeScript applications.

Documentation · API reference · Changelog · Support

Requirements

Requirement	Supported version or setup
Node.js	22 or later
Supported environments	Modern browsers, Node.js, React, React Native, Angular, Vue, and other JavaScript/TypeScript environments
React Native	Install react-native-url-polyfill alongside pubnub when using React Native.

Installation

From your JavaScript project's root directory:

npm install pubnub

Or download one of our builds from our CDN:

• https://cdn.pubnub.com/sdk/javascript/pubnub.13.1.3.js
• https://cdn.pubnub.com/sdk/javascript/pubnub.13.1.3.min.js

For other installation methods, see environment setup.

Quickstart

This example runs in Node.js 22 or later. It subscribes to hello_world, publishes one message, and prints the received text.

Get your keys

1. Open the PubNub Admin Portal.

2. Create an app and a keyset for development, or select an existing development keyset.

3. Copy its publish key and subscribe key.

If Access Manager is enabled, obtain a token from your trusted backend and call pubnub.setToken(token) before accessing protected resources. Keep the secret key and token-granting logic on the backend.

Send and receive a message

Create index.js in the project root and add:

Replace the key placeholders. Use a User ID that identifies the user or device in your app.

const PubNub = require("pubnub");

const pubnub = new PubNub({
  publishKey: "YOUR_PUBLISH_KEY",
  subscribeKey: "YOUR_SUBSCRIBE_KEY",
  userId: "hello-world-user",
});

const subscription = pubnub.channel("hello_world").subscription();
let published = false;

subscription.onMessage = (event) => {
  console.log(event.message);

  subscription.unsubscribe();
  pubnub.removeAllListeners();
  pubnub.destroy();
};

pubnub.addListener({
  status: async (status) => {
    if (status.category === PubNub.CATEGORIES.PNConnectedCategory && !published) {
      published = true;

      await pubnub.publish({
        channel: "hello_world",
        message: "Hello world",
      });
    }
  },
});

subscription.subscribe();

Run the example

node index.js

The terminal should show:

Hello world

The example calls subscription.unsubscribe(), pubnub.removeAllListeners(), and pubnub.destroy() after receiving the message. Reuse one PubNub client for the user/session rather than creating a client for every operation.

For a complete application, see the getting started guide.

Next steps

Task	Documentation
Configure the client	Configuration
Work with subscriptions and messages	Publish & Subscribe
Check channel occupancy	Presence
Read message history	Message Persistence

Build with an AI coding assistant

The PubNub MCP server gives an AI coding assistant access to PubNub SDK documentation and PubNub APIs. Connect the assistant to the hosted server at https://mcp.pubnub.com, or run npx @pubnub/mcp@latest locally.

The server repository has setup steps for VS Code, Cursor, Claude Code, Claude Desktop, Codex, Gemini CLI, and OpenCode.

Before production

Use Access Manager to grant each client the permissions it needs. Keep the secret key on your backend. Never include it in a distributed client.

Create one PubNub instance and reuse it for the lifetime of the user or application session. Call subscription.unsubscribe() when an individual subscription is no longer needed, pubnub.unsubscribeAll() to stop all subscriptions, pubnub.removeAllListeners() when registered listeners are no longer required, and pubnub.destroy() when the client itself is no longer needed.

Live delivery through PubNub SDKs is at-most-once. A subscriber can miss messages if its buffer overflows or if it is disconnected when a message is published. For recovery after longer gaps, see Message Persistence.

Troubleshooting

Symptom	Check
React Native reports URL-related errors	Install react-native-url-polyfill alongside pubnub. The SDK no longer bundles this dependency. See JavaScript Environment Setup.
A publish succeeds but no message appears	Check the message handler, subscription readiness, keyset, and channel name.
Access Manager grant APIs are unavailable in a browser build	Issue tokens from a trusted backend and call pubnub.setToken(token) in the client. The prebuilt browser SDK deliberately disables the Access Manager server module and secret-key functionality. See Configuration.
Extra clients or duplicate messages during development	Reuse the PubNub client and subscription across renders. In React, create them in lifecycle/application code and unsubscribe, remove listeners, and destroy an owned client from the corresponding cleanup instead of creating another client on every render.

For setup help, see troubleshooting. Check network status for service incidents.

Releases

Read the changelog before upgrading.

For a major version change, review the SDK-specific migration guidance linked from the JavaScript documentation and the JavaScript SDK changelog for breaking changes introduced after that guide.

Support and contributions

For setup or account help, contact PubNub Support.

For a reproducible SDK bug, use GitHub Issues. Include the SDK version, runtime, and a small reproduction with credentials removed.

Install the repository dependencies, run the relevant build and test commands for the affected package/platform, and include tests for behavioral changes before opening a pull request.

License

See the PubNub Software Development Kit License Agreement.

Support

If you need help or have a general question, contact support@pubnub.com.