Repository navigation
dependency upgrades, dataSync relationships delete event type update, readme updates #529
+439
−212
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,170 +1,161 @@ | ||
| <img width="1920" height="600" alt="image" src="https://github.com/user-attachments/assets/b60b4e27-a140-4784-8b34-85ae421023e2" /> | ||
|
|
||
| # PubNub JavaScript and TypeScript SDK | ||
|
|
||
| [](https://www.npmjs.com/package/pubnub) | ||
| 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](https://www.pubnub.com/docs/sdks/javascript) · [API reference](https://www.pubnub.com/docs/sdks/javascript/api-reference/publish-and-subscribe) · [Changelog](https://www.pubnub.com/docs/sdks/javascript/changelog) · [Support](https://support.pubnub.com/) | ||
|
|
||
| ## Requirements | ||
|
|
||
| | Requirement | Supported version or setup | | ||
| | --- | --- | | ||
| | Node.js | [22 or later](https://www.pubnub.com/docs/sdks/javascript/environment-setup) | | ||
| | Supported environments | [Modern browsers, Node.js, React, React Native, Angular, Vue, and other JavaScript/TypeScript environments](https://www.pubnub.com/docs/sdks/javascript) | | ||
| | React Native | Install `react-native-url-polyfill` alongside `pubnub` when using React Native. | | ||
|
|
||
| ## Installation | ||
|
|
||
| From your JavaScript project's root directory: | ||
|
|
||
| ```sh | ||
| 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](https://www.pubnub.com/docs/sdks/javascript/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](https://admin.pubnub.com/). | ||
|
|
||
| 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. | ||
|
|
||
| ```javascript | ||
| 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", | ||
| }); | ||
|
Comment on lines
+80
to
+83
There was a problem hiding this comment. 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: sed -n '25,85p' README.md
rg -n 'destroy\\(|unsubscribe\\(|publish\\(' --glob '!node_modules/**' .Repository: pubnub/javascript Length of output: 1766 🏁 Script executed: set +e
printf '%s\n' '--- README relevant block ---'
nl -ba README.md | sed -n '27,85p'
printf '%s\n' '--- publish declarations and calls ---'
rg -n -F --glob '!node_modules/**' -e 'publish(' -e 'async publish' -e 'publish =' src README.md tests packages 2>/dev/null
printf '%s\n' '--- lifecycle declarations and calls ---'
rg -n -F --glob '!node_modules/**' -e 'destroy()' -e 'unsubscribe()' -e 'removeAllListeners()' src README.md tests packages 2>/dev/null
printf '%s\n' '--- package metadata and relevant exports ---'
rg -n -F --glob 'package.json' -e '"name"' -e '"version"' -e '"main"' -e '"types"' .
rg -n -F --glob '!node_modules/**' -e 'class PubNub' -e 'class Subscription' -e 'destroy()' -e 'unsubscribe()' .Repository: pubnub/javascript Length of output: 45673 🏁 Script executed: printf '%s\n' '--- publish implementation ---'
nl -ba src/core/pubnub-common.ts | sed -n '1300,1395p'
printf '%s\n' '--- destroy and client lifecycle ---'
nl -ba src/core/pubnub-common.ts | sed -n '1270,1345p'
nl -ba src/core/pubnub-common.ts | sed -n '4870,4925p'
printf '%s\n' '--- subscription lifecycle ---'
nl -ba src/entities/subscription-base.ts | sed -n '160,230p'
nl -ba src/entities/subscription-base.ts | sed -n '400,520p'
printf '%s\n' '--- listener dispatch ---'
rg -n -F -- 'handleStatus' src/core/components src/core src/entities
nl -ba src/core/components/event-dispatcher.ts | sed -n '1,180p'
nl -ba src/core/components/event-dispatcher.ts | sed -n '240,330p'
printf '%s\n' '--- complete README example and lifecycle prose ---'
nl -ba README.md | sed -n '27,110p'Repository: pubnub/javascript Length of output: 31804 🏁 Script executed: printf '%s\n' '--- publish Promise path ---'
nl -ba src/core/pubnub-common.ts | sed -n '1180,1300p'
nl -ba src/core/pubnub-common.ts | sed -n '1388,1425p'
printf '%s\n' '--- listener invocation ---'
nl -ba src/core/components/event-dispatcher.ts | sed -n '325,390p'
printf '%s\n' '--- subscribe binding and update ---'
nl -ba src/entities/subscription.ts | sed -n '1,120p'
nl -ba src/entities/subscription-base.ts | sed -n '520,575p'Repository: pubnub/javascript Length of output: 15815 Bound the example and clean up on every completion path.
Suggested fix--- "a/README.md"
+++ "b/README.md"
@@ -41,31 +41,51 @@
userId: "hello-world-user",
});
const subscription = pubnub.channel("hello_world").subscription();
let published = false;
+const cleanup = () => {
+ subscription.unsubscribe();
+ pubnub.removeAllListeners();
+ pubnub.destroy();
+};
+let rejectMessage;
+let timeoutId;
-subscription.onMessage = (event) => {
- console.log(event.message);
+const messageReceived = new Promise((resolve, reject) => {
+ rejectMessage = reject;
+ timeoutId = setTimeout(() => reject(new Error("Timed out waiting for message")), 10000);
- subscription.unsubscribe();
- pubnub.removeAllListeners();
- pubnub.destroy();
-};
+ subscription.onMessage = (event) => {
+ console.log(event.message);
+ resolve();
+ };
+});
pubnub.addListener({
status: async (status) => {
if (status.category === "PNConnectedCategory" && !published) {
published = true;
- await pubnub.publish({
- channel: "hello_world",
- message: "Hello world",
- });
+ try {
+ await pubnub.publish({
+ channel: "hello_world",
+ message: "Hello world",
+ });
+ } catch (error) {
+ rejectMessage(error);
+ }
}
},
});
subscription.subscribe();
+
+messageReceived
+ .catch((error) => console.error("Example failed:", error))
+ .finally(() => {
+ clearTimeout(timeoutId);
+ cleanup();
+ });
```
Run the example:🤖 Prompt for AI Agents |
||
| } | ||
| }, | ||
| }); | ||
|
|
||
| subscription.subscribe(); | ||
| ``` | ||
|
|
||
| ### Run the example | ||
|
|
||
| ```sh | ||
| node index.js | ||
| ``` | ||
|
|
||
| The terminal should show: | ||
|
|
||
| ```text | ||
| 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](https://www.pubnub.com/docs/sdks/javascript). | ||
|
|
||
| ## Next steps | ||
|
|
||
| | Task | Documentation | | ||
| | --- | --- | | ||
| | Configure the client | [Configuration](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration) | | ||
| | Work with subscriptions and messages | [Publish & Subscribe](https://www.pubnub.com/docs/sdks/javascript/api-reference/publish-and-subscribe) | | ||
| | Check channel occupancy | [Presence](https://www.pubnub.com/docs/sdks/javascript/api-reference/presence) | | ||
| | Read message history | [Message Persistence](https://www.pubnub.com/docs/sdks/javascript/api-reference/storage-and-playback) | | ||
|
|
||
| ## 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](https://github.com/pubnub/pubnub-mcp-server) has setup steps for VS Code, Cursor, Claude Code, Claude Desktop, Codex, Gemini CLI, and OpenCode. | ||
|
|
||
| ## Before production | ||
|
|
||
| Use [Access Manager](https://www.pubnub.com/docs/sdks/javascript/api-reference/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](https://www.pubnub.com/docs/sdks/javascript/api-reference/storage-and-playback). | ||
|
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win Qualify the at-most-once delivery statement. Line 106 does not limit the guarantee to a stable connection. After reconnect, the SDK can replay a message with the same timetoken, so a handler may receive it again. State the stable-connection qualification and mention possible replay after reconnect. (pubnub.com) 🤖 Prompt for AI Agents |
||
|
|
||
| ## 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](https://www.pubnub.com/docs/sdks/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](https://www.pubnub.com/docs/sdks/javascript/api-reference/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](https://www.pubnub.com/docs/sdks/javascript). Check [network status](https://status.pubnub.com/) for service incidents. | ||
|
|
||
| ## Releases | ||
|
|
||
| Read the [changelog](https://www.pubnub.com/docs/sdks/javascript/changelog) before upgrading. | ||
|
|
||
| For a major version change, review the SDK-specific migration guidance linked from the JavaScript documentation and the [JavaScript SDK changelog](https://www.pubnub.com/docs/sdks/javascript/changelog) for breaking changes introduced after that guide. | ||
|
|
||
| ## Support and contributions | ||
|
|
||
| For setup or account help, contact [PubNub Support](https://support.pubnub.com/). | ||
|
|
||
| For a reproducible SDK bug, use [GitHub Issues](https://github.com/pubnub/javascript/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](https://github.com/pubnub/javascript/blob/master/LICENSE). | ||
|
|
||
|
|
||
| ## Support | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
Repository: pubnub/javascript
Length of output: 23457
🏁 Script executed:
Repository: pubnub/javascript
Length of output: 17053
Align the Node.js requirement with
package.json.The active v13.1.3 release metadata still advertises Node.js 8. Update both Node artifact requirements and all six platform runtime entries to Node.js 22 or later.
Suggested fix
Apply the same replacements to both
min-versionentries and all sixruntime-versionentries.🤖 Prompt for AI Agents