QPub JavaScript SDK

QPub is a pub/sub channels cloud. This is the official JavaScript client library, including both real-time and REST interfaces.

To meet QPub and see more info and examples, please read the documentation.

Getting Started

Follow these steps to just start building with QPub in JavaScript or see the Quickstart guide which covers more programming languages.

Install with package manager

Use any package manager like npm or yarn to install the JavaScript SDK.

Npm:

npm i @qpub/sdk

Yarn:

yarn add @qpub/sdk

Import as ES module:

import { QPub, Message } from "@qpub/sdk";

Import from CDN:

<script src="https://cdn.jsdelivr.net/npm/@qpub/sdk@latest/build/qpub.umd.js"></script>

Interacting with QPub

Get your API key from QPub dashboard by creating a new project or use existing one.

Connect to QPub:

const socket = new QPub.Socket({ apiKey: "YOUR_API_KEY" });

Subscribe to a channel and listen for any data publishing to receive:

let channel = socket.channels.get("my-channel");
channel.subscribe((message: Message) => {
    console.log({ message });
});

Publish a message:

channel.publish("Hello!");

Publish a message with REST interface:

const rest = new QPub.Rest({ apiKey: "YOUR_API_KEY" });

let channel = rest.channels.get("my-channel");

channel.publish("Hello!");

Publish batch messages:

rest.channels
    .publishBatch(
        ["myChannel", "another-channel"],
        [
            { data: "Hello World 1", event: "fooEvent" },
            { data: "Hello World 2", event: "barEvent" },
            { data: "Hello World 3", event: "barEvent" },
        ]
    )
    .then((result) => {
        console.log(result);
    })
    .catch((err) => {
        console.error(`Error: ${err}`);
    });

React Integration

QPub includes built-in React hooks and components for real-time socket connections.

Use manual subscription with proper cleanup for reliable message handling:

import React, { useCallback, useEffect } from "react";
import { SocketProvider, useChannel, useConnection, Message } from "@qpub/sdk/react";

function App() {
    return (
        <SocketProvider options={{ apiKey: "YOUR_API_KEY" }}>
            <ChatRoom />
        </SocketProvider>
    );
}

function ChatRoom() {
    const { status } = useConnection();
    const { publish, subscribe, unsubscribe, ready } = useChannel("my-channel");

    const handleMessage = useCallback((message: Message) => {
        console.log("Received:", message);
    }, []);

    useEffect(() => {
        if (ready) {
            subscribe(handleMessage);

            return () => {
                unsubscribe();
            }
        }
    }, [channelStatus, subscribe, unsubscribe, handleMessage]);

    return (
        <div>
            <div>Connection: {status}</div>
            <div>Channel ready: {ready ? "✅" : "⏳"}</div>
            <button
                onClick={() => publish("Hello from Socket!")}
                disabled={!ready}
            >
                Send Message
            </button>
        </div>
    );
}

See React Documentation for complete guide.

Token Authentication

QPub provides three methods for secure token generation with different security levels. Learn more in the Token Authentication Guide:

• generateToken() - Quick server-side token generation
• issueToken() - Server-validated token generation
• createTokenRequest() + requestToken() - Secure client-server token exchange (recommended)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup and workflow
• Code standards and best practices
• Testing guidelines
• Pull request process
• Release workflow (for maintainers)

Quick Start for Contributors

# Clone and setup
git clone [email protected]:qpubio/qpub-js.git
cd qpub-js
npm install

# Run tests
npm test

# Build locally
npm run build

For detailed instructions, see the Contributing Guide.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.