Pusher

Pusher Channels is a hosted service for pushing messages to connected browsers and apps over WebSockets. In a MainSDK app it is the default driver behind realtime: your server calls realtime.publish(), and clients listening with realtime.subscribe() get the update without a refresh. Pick Pusher for live order status, dashboards and badges when you don't want to run your own WebSocket servers.

realtime:
  driver: pusher

Before you start

1. Create a Channels app in your Pusher account. Each app has an app ID, a key, a secret and a cluster (the region it runs in).
2. Pick the cluster closest to your users and, where it matters, in your MainSDK data region (US, EU or India).
3. Create one app per environment, so development traffic never reaches production clients.

The key is public by design; the secret is not. Store the secret in your secrets manager, never in code or the browser.

Configure

realtime:
  driver: pusher

How the Pusher driver takes its app ID, key, secret and cluster is not decided yet; the secret will be a secret: reference such as secret:PUSHER_SECRET (suggested name).

Use it

"use server";
import { realtime } from "mainsdk";

export async function markShipped(orderId: string) {
  // update the order in db first
  await realtime.publish(`order:${orderId}`, { status: "shipped" });
}

On the client, realtime.subscribe() listens on the channel, for example order:ord_1; its exact signature arrives with the spec.

Local development and testing

• createTestApp() from @mainsdk/testing runs realtime on its in-memory fake, so tests need no Pusher account.
• chaos.on("realtime", { outage: true }) simulates a Pusher outage.
• Pusher's debug console shows messages on a development app as they are sent.

What MainSDK adds on top

• Channel access checked per user and tenant, so a client only hears channels it may see. On Pusher, per-user access is what private channels are for; how MainSDK wires their authorisation step is not decided yet.
• A new realtime update can go to a small share of users first and pause itself on spikes in errors, through the same staged rollout as notifications.

See Real-time updates.

Limits and notes

• realtime is listed for phase 1, with no spec yet. How channel access rules are declared is not decided.
• Keep personal data out of messages; send IDs and statuses and let the client fetch details.
• Pusher limits message size and connection counts by plan; check yours against your traffic.

Swap to or from it

realtime:
  driver: ably   # was pusher

Broadcast holds no state in the provider, so it swaps with no migration. See Swap a driver.

FAQ

Can clients publish to a channel? Not through the catalog calls: clients subscribe and your server broadcasts.

Does Pusher give me presence? Real-time collaboration and presence in MainSDK come in phase 5.

Next

• Real-time updates
• Ably and Supabase
• Swap a driver

Open questions