@smallstack/web-component-sdk

Typed bridge client for third-party web components running inside the smallstack Business Platform sandbox. Use it instead of raw postMessage.

The major version tracks the bridge protocol version (SDK 1.x ⇄ protocol 1).

Usage

import { connect } from "@smallstack/web-component-sdk";

class MyWidgetElement extends HTMLElement {
	#client;
	#cleanup = [];

	async connectedCallback() {
		const shadow = this.attachShadow({ mode: "open" });
		this.#client = connect(this);
		// platform theme (daisyUI tokens, light/dark) — kept in sync live
		this.#cleanup.push(this.#client.adoptThemeStylesheets(shadow));
		// auto-report height so the host iframe sizes itself
		this.#cleanup.push(this.#client.observeResize());

		const { grantedScopes } = await this.#client.whenInitialized();
		const profile = this.#client.getUserProfile(); // user-profile:read
		this.#client.onData(() => {
			// collection data, keyed by the widget-config property bound at
			// placement time (see the collection:{configurationProperty}:{action}
			// scope scheme)
			const orders = this.#client.getCollection("orders");
			// ...render
		});
	}

	disconnectedCallback() {
		for (const cleanup of this.#cleanup) cleanup();
		this.#client?.disconnect();
	}
}

Testing your component

WebComponentMockHost emulates the platform host page (handshake, data pushes, theme switches) for unit tests and the local dev harness:

import { WebComponentMockHost } from "@smallstack/web-component-sdk";

const host = new WebComponentMockHost(element);
host.init({ grantedScopes: ["user-profile:read"], data: { userProfile } });
host.pushData({ orders: [{ id: "o1" }] });
host.pushTheme({ name: "dark", dark: true });
const resize = await host.waitForMessage("resize");

Protocol package

The wire protocol lives in its own zero-dependency package, @smallstack/web-component-bridge-protocol, which this SDK depends on and re-exports. That package is the single source of truth: the platform (@smallstack/shared in smallstack/business-platform) will re-export the same module once it adopts the package — a follow-up to the initial publish — replacing today's hand-synced copy so there is no mirror to keep in sync.

The SDK's major version tracks the protocol package's major (SDK 1.x ⇄ protocol 1). A breaking envelope change is a major bump of the protocol package and of this SDK; a stale bundle carries the old version and is rejected at the boundary. See the protocol package README for the full release rule.