@platform/sdk-react

The official, optional React adapter for @platform/sdk — thin hooks over the core’s public API. Install it only on React:

npm install @platform/sdk @platform/sdk-react

It declares react: >=18 as a peerDependency, resolved against your app’s own React. The core works without it — see Framework adapters.

Usage

InvoiceSurface + DraftRow

import { defineStateChannel, type SurfaceConnection } from "@platform/sdk";
import { useStateChannel, useSurfaceActivate, useSurfaceParams } from "@platform/sdk-react";

interface Draft {
  id: string;
  name: string;
}

const draftChannel = (id: string) => defineStateChannel<Draft>(`draft:${id}`);

// A surface. useSurfaceActivate self-sizes it (attach the returned ref to the root element);
// useSurfaceParams reads typed params and re-renders when the host re-parameterises in place.
export function InvoiceSurface({ conn }: { conn: SurfaceConnection }) {
  const ref = useSurfaceActivate(conn);
  const { customerEmail = "" } = useSurfaceParams<{ customerEmail?: string }>(conn);
  return <div ref={ref}>Invoices for {customerEmail}</div>;
}

// A parent that mirrors another frame's live draft via useStateChannel (unsubscribed on unmount).
export function DraftRow({ conn, id }: { conn: SurfaceConnection; id: string }) {
  const draft = useStateChannel(draftChannel(id), conn.state);
  return <b>{draft?.name}</b>;
}

API

useSurfaceActivate<T>(conn): RefObject<T>

Returns a ref; attach it to the surface’s root element and the hook calls conn.activate once on mount (observe + ready, one frame later so custom elements have upgraded). Replaces the hand-rolled useRef + useEffect(observe + ready).

useSurfaceParams<P>(conn): P

Read the surface’s params typed as P, re-rendering when the host re-parameterises the surface in place. Replaces the manual useState(conn.params as …) + onParams subscription.

useStateChannel<S>(channel, state): S | undefined

Mirror a cross-frame StateChannel into React state, seeded from the channel’s current snapshot and unsubscribed on unmount.

See also

• Embedded surfaces and Cross-frame state — the core mechanics these hooks wrap.