@salesforce/emp-api (Beta)

Beta: This is a pilot or beta service subject to the Beta Services Terms or a written Unified Pilot Agreement, and applicable terms in the Product Terms Directory.

An empApi-shaped wrapper (subscribe, unsubscribe, onError) for the platform's CometD/Bayeux streaming engine, so a UI Bundle can react to Platform Events and Change Data Capture (CDC) events without polling.

Provides the same functionality of lightning/empApi for ui-bundles.

Like the lightning/empApi module, @salesforce/emp-api is supported only in desktop browsers and requires API version 65.0 or later. For use in Lightning Experience only.

Installation

npm install @salesforce/emp-api

Usage

import { subscribe } from "@salesforce/emp-api";

const subscription = await subscribe(
  "/data/Account__ChangeEvent", // or a Platform Event channel, e.g. "/event/Foo__e"
  -1, // replayId: -1 = new events only, -2 = replay retention window, or a specific id
  (message) => {
    console.log(message.channel, message.data.payload);
  },
);

// later
subscription.unsubscribe();

import { onError } from "@salesforce/emp-api";

const removeListener = onError((message) => {
  // Handle connection/transport errors, including a subscribe failure
  // (e.g. an invalid channel).
});

// later, to stop this listener from receiving further errors
removeListener();

API

• subscribe(channel, replayId, onMessage) — Subscribes to a Platform Event or CDC channel. Resolves once the streaming engine is configured and the subscription is registered (it does not wait for a server ack). Two calls on the same channel produce two independent subscriptions.
• unsubscribe(subscription) — Also available as subscription.unsubscribe(). Synchronous, and a no-op if already unsubscribed.
• onError(callback) — Registers a listener for engine-level errors. Per-channel and later transport failures surface here, not through the subscribe() promise. Returns a function that removes this listener.
• isEmpEnabled() — Resolves true if this browsing context has Worker support, false if it doesn't. Resolves false, never rejects, if the streaming config can't be fetched for any reason.
• setDebugFlag(flag) — Passes flag through to the underlying engine to enable/disable console diagnostics. Inherited quirk: if localStorage['emp.debugFlag'] was already "true" when the page loaded, this becomes a no-op for the rest of that page session — even setDebugFlag(false) won't turn it off until the page is reloaded with that key cleared or changed. This call still best-effort writes flag to that same localStorage key, so a future page load picks it up.

Messages delivered to onMessage are one of two shapes — a Platform Event message, or a Change Data Capture message whose payload carries a ChangeEventHeader (fields per Salesforce's Change Data Capture Developer Guide):

interface PlatformEventMessage {
  channel: string;
  data: {
    schema?: string;
    payload: Record<string, unknown>;
    event: { replayId: number; EventUuid?: string };
  };
}

interface ChangeDataCaptureMessage {
  channel: string;
  data: {
    schema?: string;
    payload: { ChangeEventHeader: ChangeEventHeader } & Record<string, unknown>;
    event: { replayId: number };
  };
}

Use isChangeDataCaptureMessage(message) to narrow — the channel string alone isn't a reliable discriminant, since the aggregate /data/ChangeEvents channel carries CDC messages for multiple entities:

import { isChangeDataCaptureMessage, subscribe } from "@salesforce/emp-api";

await subscribe("/data/ChangeEvents", -1, (message) => {
  if (isChangeDataCaptureMessage(message)) {
    console.log(message.data.payload.ChangeEventHeader.changeType);
  }
});

Configuration

Before the engine can start, it needs a CometD URL and worker script path. These are resolved automatically from the platform's GraphQL API via getStreamingConfig — this is an internal implementation detail of subscribe(), not something callers can override.

Vendored engine

This package wraps the platform's CometD/Bayeux client, vendored unedited under src/vendor (original copyright preserved). It does not modify the vendored engine's internal logic.