Skip to content
plasma

@sh1n4ps/plasma-devtools

@sh1n4ps/plasma-devtools gives you three ways to inspect a running plasma client: an in-page React panel, a state-snapshot hook for custom UI, and a window.postMessage bridge for a Chrome DevTools extension.

What’s here

Section titled “What’s here”
  • PlasmaDevtools — the drop-in React panel component.
  • PlasmaDevtoolsProps — the panel’s props:
    • client — the PlasmaClient to inspect
    • dbName — the IDB database name (used to open the base / outbox / blob stores for the panel display)
    • schema — the schema, so the panel can decode encoded row values in the outbox
    • refreshIntervalMs (default 500ms) — polling cadence
    • position (default "bottom-right") — corner: one of "bottom-right" / "bottom-left" / "top-right" / "top-left"
  • useDevtoolsSnapshot — polling hook that returns the current sync state (clientID, cookie, outbox, schemaVersion).
  • DevtoolsSnapshot — the return type of the hook.
  • attachDevtoolsBridge — attaches a window.postMessage bridge so an external inspector can observe and control the client.
  • AttachOptions — the bridge configuration:
    • dbName, schema — same purpose as the panel props
    • refreshIntervalMs (default 500ms) — how often the bridge broadcasts state-update messages
    • targetOrigin (default "*") — origin whitelist for outgoing postMessage calls
    • allowedOrigins (default "same-origin") — origins allowed to SEND commands to the page. Default protects against cross-frame reset-local-state attacks — widen only to trusted extension origins
    • runtime (default { name: "@sh1n4ps/plasma-client", version: "unknown" }) — identity broadcast in the initial hello message so extensions can match versions
  • Protocol types — DevtoolsMessage (union), HelloMessage, StateUpdateMessage, CommandMessage, CommandResultMessage, DevtoolsStateSnapshot.
  • isDevtoolsMessage — brand check for postMessage receivers.
  • PLASMA_DEVTOOLS_SOURCE — the constant "plasma-devtools" used as the source field on every message.

Key patterns

Section titled “Key patterns”
// Drop the panel into a dev-only render.
{import.meta.env.DEV && (
  <PlasmaDevtools client={plasma} dbName="app" schema={schema} />
)}


// Or build your own status widget.
function SyncStatus() {
  const snap = useDevtoolsSnapshot(plasma, { dbName: "app", schema })
  return <span>Outbox: {snap.outbox.length}</span>
}


// Or wire the bridge for a Chrome extension.
const dispose = attachDevtoolsBridge(plasma, {
  dbName: "app",
  schema,
  allowedOrigins: ["chrome-extension://your-extension-id"],
})

Full symbol index

Section titled “Full symbol index”

Under reference/generated/plasma-devtools/src.

Where to go from here

Section titled “Where to go from here”