@statelyai/sdk

Embed the Stately editor in your app. Zero dependencies, fully typed.

Install

npm install @statelyai/sdk

API key

An API key is required to use the embed SDK. To get one:

1. Go to your Stately settings
2. Select the API Key tab
3. Click Create API Key (Project or Account scope)
4. Copy and store it securely

See the Studio API docs for more details.

Quick start

import { createStatelyEmbed } from '@statelyai/sdk';

const embed = createStatelyEmbed({
  baseUrl: 'https://stately.ai',
  apiKey: 'your-api-key',
});

// Mount into a container
embed.mount(document.getElementById('editor')!);

// Initialize with a machine
embed.init({
  machine: myMachineConfig,
  mode: 'editing',
  theme: 'dark',
});

API

createStatelyEmbed(options)

Creates an embed instance.

| Option | Type | Description | |--------|------|-------------| | baseUrl | string | Required. Base URL of the Stately app | | apiKey | string | Required. Your Stately API key | | origin | string | Custom target origin for postMessage | | onReady | () => void | Called when embed is ready | | onLoaded | (graph) => void | Called when machine is loaded | | onChange | (graph, machineConfig) => void | Called on every change | | onSave | (graph, machineConfig) => void | Called on save | | onError | ({ code, message }) => void | Called on error |

Embed methods

mount(container) / attach(iframe)

Mount creates an iframe inside a container element. Attach connects to an existing iframe.

// Create a new iframe
const iframe = embed.mount(document.getElementById('editor')!);

// Or attach to an existing one
embed.attach(document.querySelector('iframe')!);

init(options)

Initialize the embed with a machine and display options.

embed.init({
  machine: machineConfig,
  format: 'xstate', // optional
  mode: 'editing',  // 'editing' | 'viewing' | 'simulating'
  theme: 'dark',    // 'light' | 'dark'
  readOnly: false,
  depth: 3,
  panels: {
    leftPanels: ['code'],
    rightPanels: ['events'],
    activePanels: ['code'],
  },
});

updateMachine(machine, format?)

Update the displayed machine.

setMode(mode) / setTheme(theme)

Change the embed mode or theme at runtime.

export(format, options?)

Export the current machine. Returns a promise.

const code = await embed.export('xstate', { version: 5 });
const json = await embed.export('json');
const mermaid = await embed.export('mermaid');

Supported formats: xstate, json, digraph, mermaid, scxml

on(event, handler) / off(event, handler)

Subscribe/unsubscribe to embed events: ready, loaded, change, save, error.

embed.on('change', ({ graph, machineConfig }) => {
  console.log('Machine changed', machineConfig);
});

toast(message, type?)

Show a toast notification in the embed. Type: 'success' | 'error' | 'info' | 'warning'

destroy()

Tear down the embed. Removes listeners, rejects pending promises, and removes the iframe if it was created via mount().