Reference

JS API: window.WPS

The plugin exposes window.WPS on all pages where the client script is loaded.

If you are building a WordPress block or script with a build tool, add 'wpsignal' as a dependency in your wp_enqueue_script call to ensure WPS loads first.

Quick example

// Listen for a specific event
const unsub = WPS.on('post.updated', (data, channel) => {
    console.log('Post updated on', channel, data.post_title);
});

// OR use native DOM events
document.addEventListener('wpsignal:post.updated', (e) => {
    console.log(e.data.post_title);
});

// Unsubscribe later
unsub();

WPS.subscribe( channels )

Subscribe to additional channels on the shared connection.

Parameter	Type
channels	string[]

WPS.unsubscribe( channels )

Unsubscribe from channels.

Parameter	Type
channels	string[]

WPS.publish( channel, event, data? )

Publish a JSON message through the WebSocket. No-ops on SSE (one-way transport).

Parameter	Type
channel	string
event	string
data?	Record< string, unknown >

WPS.publishBinary( channel, data )

Send a raw binary frame to the server over the WebSocket. Frame format: 2-byte BE channel name length + channel bytes + payload. No-ops on SSE (one-way transport) or when not connected.

Parameter	Type
channel	string
data	Uint8Array

WPS.setPresence( channel, state )

Enter or update connection-scoped presence on a channel. The relay drops the membership the instant this socket closes, and the client re-sends it on reconnect; pass null to leave, which is announced at once. Subscribers of the channel receive `wps.presence` join/leave/sync events (`channel` is the site-relative name, `woo:carts:live`). Requires WebSocket; no-op on SSE.

Parameter	Type
channel	string
state	Record< string, unknown > \| null

WPS.on( event, handler )

() => void

Parameter	Type
event	string
handler	WPSEventHandler

WPS.onMessage( handler )

() => void

Parameter	Type
handler	WPSMessageHandler

WPS.onBinaryMessage( handler )

() => void

Parameter	Type
handler	WPSBinaryHandler

WPS.connected

readonly property boolean

Whether the connection is currently open.

WPS.transport

readonly property WPSTransportName | null

Current transport layer, or null while still connecting.

WPS.status

readonly property WPSStatus

Current transport state and capabilities.

WPS.onConnectionChange( handler )

() => void

Parameter	Type
handler	( connected: boolean ) => void

WPS.onStateChange( handler )

() => void

Parameter	Type
handler	( state: WPSConnectionState ) => void

WPS.state

readonly property WPSConnectionState

The current connection state, as delivered to onStateChange.

WPS.uuid( )

string

A version-4 UUID. Works on plain HTTP pages too, where `crypto.randomUUID` does not exist (it needs a secure context); use it instead of calling `crypto.randomUUID()` directly. Needs no connection.

WPS.visitorId( )

string

This browser's stable id, kept in localStorage and shared by every tab and every extension on the site, for counting people rather than sockets (pass it in presence state). It names a browser, not a person; when storage is blocked it lasts for the page load only.

WPS.onChannel( channel, expected )

boolean

Whether an event's `channel` is the `expected` one, given by its site-relative name (`woo:stock`); the qualified `site:{id}:woo:stock` matches too. Any tokened browser may publish on a public channel, so check this in a handler before trusting the event's data.

Parameter	Type
channel	string
expected	string

Handler types

These types are used as parameters in the methods above.

WPSEventHandler
Used in WPS.on()

type WPSEventHandler = ( data: Record< string, unknown >, channel: string ) => void;

WPSMessageHandler
Used in WPS.onMessage()

type WPSMessageHandler = ( event: string, data: Record< string, unknown >, channel: string ) => void;

WPSBinaryHandler
Used in WPS.onBinaryMessage()

Handler for incoming binary WebSocket frames (e.g. Yjs updates).

type WPSBinaryHandler = ( channel: string, data: Uint8Array ) => void;

Connection state

The shapes handed to WPS.onStateChange() and returned by WPS.state. WPSConnectionErrorCode mirrors @wordpress/sync, so the block editor can pick its own copy for each case without translating anything.

WPSTransportName

type WPSTransportName = 'ws' | 'sse';

WPSConnectionErrorCode

Error codes shared with the Yjs provider. They mirror @wordpress/sync's ConnectionErrorCode so the editor can pick its copy without translation.

type WPSConnectionErrorCode =
  | 'authentication-failed'
  | 'connection-expired'
  | 'connection-limit-exceeded'
  | 'document-size-limit-exceeded'
  | 'protocol-mismatch'
  | 'unknown-error';

WPSConnectionError

interface WPSConnectionError {
  code: WPSConnectionErrorCode;
  message: string;
}

WPSConnectionState

Full connection state delivered to `onStateChange` handlers.

interface WPSConnectionState {
  connected: boolean;
  transport: WPSTransportName | null;
  /** Present while disconnected because of an error. */
  error?: WPSConnectionError;
  /** Present while an automatic retry is scheduled: milliseconds until it fires. */
  retryInMs?: number;
  /** Consecutive failed attempts since the last successful open. */
  failures: number;
}

WPSStatus

type WPSStatus = {
  name: WPSTransportName | null;
  connected: boolean;
  readyState: number | null;
  canPublish: boolean;
  canPublishBinary: boolean;
  /** Timestamp (ms) of the last inbound frame (including server pings); null when unknown or on SSE. */
  lastMessageAt: number | null;
  /** Why the connection is down, if it is; cleared on the next successful open. */
  lastError: WPSConnectionError | null;
  /** Consecutive failed connection attempts since the last successful open. */
  failures: number;
};

DOM CustomEvents

For every received message the client also dispatches a CustomEvent on document. The event name is wpsignal:{event}. Use these when you prefer the standard DOM event model, or when your script may run before the client has loaded: WPS.on() is the shorter form everywhere else.

document.addEventListener('wpsignal:post.updated', (e) => {
    // e.data is the payload, e.channel the channel it arrived on
    // (both also under e.detail, as { channel, data }).
    console.log(e.channel, e.data);
});

JS API: window.WPS

WPS.subscribe( channels )

WPS.unsubscribe( channels )

WPS.publish( channel, event, data? )

WPS.publishBinary( channel, data )

WPS.setPresence( channel, state )

WPS.on( event, handler )

WPS.onMessage( handler )

WPS.onBinaryMessage( handler )

WPS.connected

WPS.transport

WPS.status

WPS.onConnectionChange( handler )

WPS.onStateChange( handler )

WPS.state

WPS.uuid( )

WPS.visitorId( )

WPS.onChannel( channel, expected )

Handler types

Connection state

DOM CustomEvents

Next steps

Getting Started

PHP API

Explorer