Quickstart
Get a working pub/sub loop 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 the sample language — code and notes update together.
Prerequisites
- A QPub account and project
- An API key from QPub Cloud
- Node.js, Bun, or a browser environment
- Node.js or Bun for bundling React apps
- Go 1.22 or newer and a module (
go mod initin your project) QPUB_API_KEYin the environment for samples (publicId:secret)
1. Install
npm install @qpub/sdkImport providers and hooks from @qpub/sdk/react (same package).
go get github.com/qpubio/[email protected]
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.
Run on a trusted server or local process that can hold the API key secret. For untrusted clients, use token auth.
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.
QPub's React hooks/providers (@qpub/sdk/react) are Socket-only. REST is recommended for server-side use, so there's no dedicated React integration — but you can still call the plain QPub.Rest client from React (an event handler or server action). Keep secrets off the public client bundle — use a JWT / token request for browsers.
REST publish is server-side only; use the Socket client to subscribe in realtime.
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,
});