Quickstart
Get a working pub/sub loop with @qpub/sdk in a few minutes. Use the API and Language controls (right rail on large screens; on smaller screens, open the docs navigation drawer at the bottom of the page) to switch Socket vs REST and JavaScript vs React — samples and notes update together.
Prerequisites
- A QPub account and project
- An API key from the dashboard
- Node.js, Bun, or a browser environment
1. Install
npm install @qpub/sdk
Import providers and hooks from @qpub/sdk/react (same package).
2. Receive or publish
Subscribe over the WebSocket client. By default the Socket connects automatically (autoConnect: true) to wss://socket.qpub.io/v1.
import { QPub } from "@qpub/sdk";
const socket = new QPub.Socket({
apiKey: process.env.QPUB_API_KEY,
});
socket.connection.on("connected", async () => {
const channel = socket.channels.get("demo");
await channel.subscribe((message) => {
console.log("received", message.data, message.event);
});
});Do not put a production API key secret in a public browser app. Use token auth instead.
Prefer a JWT or token request in SocketProvider options instead of embedding a production API key secret in the browser bundle.
Publish over HTTP with the REST client (https://rest.qpub.io/v1). REST does not open a realtime subscription — switch to Socket above to receive messages.
import { QPub } from "@qpub/sdk";
const rest = new QPub.Rest({
apiKey: process.env.QPUB_API_KEY,
});
await rest.channels.get("demo").publish(
{ text: "Hello, QPub!" },
{ event: "greeting" }
);Run this from a trusted server or script that can hold the API key secret.
Call REST from an event handler or server action. Keep secrets off the public client bundle — use a JWT / token request for browsers.
3. Complete the loop
In another process (or tab), publish with REST:
import { QPub } from "@qpub/sdk";
const rest = new QPub.Rest({
apiKey: process.env.QPUB_API_KEY,
});
await rest.channels.get("demo").publish(
{ text: "Hello, QPub!" },
{ event: "greeting" }
);
Or publish from the same Socket after you are connected:
await socket.channels.get("demo").publish(
{ text: "Hello from socket" },
{ event: "greeting" }
);Your publish call above is enough for the REST path. To see messages arrive in realtime, switch API to Socket and run the subscribe sample (or open a second client).
4. Optional: event filter
await channel.subscribe(
(message) => console.log(message.data),
{ event: "greeting" }
);Event filters apply on the subscriber (Socket). Pass { event: "greeting" } as the second argument to publish so subscribers that filter on that event receive the message.
Local development
Override hosts when pointing at a local QPub stack:
const socket = new QPub.Socket({
apiKey: process.env.QPUB_API_KEY,
wsHost: "localhost",
wsPort: 8131,
isSecure: false,
});
const rest = new QPub.Rest({
apiKey: process.env.QPUB_API_KEY,
httpHost: "localhost",
httpPort: 8111,
isSecure: false,
});