Stately

Stately for VS Code opens the Stately visual editor next to your source file so you can inspect and edit supported state models without leaving your workspace.

Features

• Open a visual editor from supported source files.
• Edit state machines visually and save changes back to code.
• Refresh the visual editor from saved source changes.
• Sign in with Stately OAuth when the editor host requires authentication.
• Free accounts open read-only root-level views.
• Export extension logs when visual/code sync fails.
• Preserve existing authoring style where possible.

Supported Files

• XState JavaScript and TypeScript
• JSON and JSONC
• YAML
• Amazon States Language
• Redux Toolkit slices
• Zustand stores
• Mermaid diagrams

Usage

1. Open a supported file in VS Code.
2. Run Stately: Open Visual Editor from the command palette or editor title menu.
3. The editor panel opens with neutral loading status while stored credentials are restored. Browser sign-in appears only when authentication is needed; if a stored OAuth credential is rejected, it is refreshed when possible or replaced through browser sign-in.
4. If prompted, complete browser sign-in. The open panel receives the credential and loads the machine automatically.
5. Save changes in VS Code to update the visual editor, or save in the visual editor to update your source file.

Commands

• Stately: Open Visual Editor
• Stately: Sign In
• Stately: Use API Key
• Stately: Sign Out
• Stately: Export Logs

Configuration

• statelyai.editorUrl: base URL for the Stately visual editor embed. Defaults to https://editor.stately.ai.
• statelyai.allowUnauthorizedEditorTls: allow self-signed or otherwise untrusted TLS certificates when the extension calls a non-local configured editor host. Defaults to false. Loopback localhost hosts are handled automatically for local development.
• statelyai.roundTripStatelyMetadata: persist @statelyai.* metadata such as colors and icons back into source code when saving from the visual editor. Defaults to true.
• statelyai.syncBackend: choose where sync conversion runs, local or remote. Defaults to local.
• statelyai.syncMaxFiles: maximum number of workspace source files included in each sync conversion. Defaults to 150.
• statelyai.syncMaxBytes: maximum total source bytes included in each sync conversion. Defaults to 50000000.

For local extension development, set statelyai.editorUrl in workspace settings.

The Run and Debug picker exposes three F5 modes:

• Run Extension (Auth)
• Run Extension (No Auth, Restricted Access) for free-plan read-only and single-level behavior
• Run Extension (Beta: No Auth, Full Access)

For the development-only beta VSIX, run pnpm vsix:beta. The beta skips authentication and grants full local editor capabilities. This behavior is fixed at build time and is unavailable in normal Marketplace builds. Do not publish the beta artifact.

End-to-end tests

Run pnpm test:e2e from this directory. The suite exercises activation, commands, CodeLens, webview opening, and bidirectional source/editor saves on both the minimum and current supported VS Code versions. It then installs the production VSIX into a clean Extension Host and verifies the packaged artifact.

Playwright's VS Code downloads are cached under .vscode-test. Linux requires a display, so use xvfb-run -a pnpm test:e2e in CI or other headless sessions.

License

Stately Editor is proprietary software. It is free to install, with available features determined by your Stately account and plan. See the bundled LICENSE file or the License tab on the Marketplace listing.