Visualize a machine definition

This guide shows you how to generate a read-only Mermaid diagram from a machine definition.

Install the Node platform implementation used to write the generated diagram:

pnpm add @effect/platform-node

Project the definition, then write it through Effect's FileSystem service:

import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
import * as NodeRuntime from "@effect/platform-node/NodeRuntime"
import * as Effect from "effect/Effect"
import * as FileSystem from "effect/FileSystem"
import * as Graph from "effect-state-machine/Graph"
import * as Mermaid from "effect-state-machine/Mermaid"
import { definition } from "./checkout.js"

const program = Effect.gen(function* () {
  const graph = Graph.fromDefinition(definition)
  const diagram = Mermaid.render(graph)
  const fileSystem = yield* FileSystem.FileSystem

  yield* fileSystem.writeFileString("checkout.mmd", diagram)
  yield* Effect.log("Wrote checkout.mmd")
}).pipe(Effect.provide(NodeFileSystem.layer))

NodeRuntime.runMain(program.pipe(Effect.orDie))

The resulting file starts with stateDiagram-v2 and includes nodes, event transitions, outcome transitions, guard order, ignored events, region paths, timers, work kinds and lanes, retry names, and child links present in the definition.

No machine instance is started and no Effect is executed. If source maps are part of your build pipeline, pass a mapSource function to Graph.fromDefinition to translate generated locations before exposing editor links.

Inspect the graph interactively

Studio projects the same immutable definition into an interactive graph and adds runtime activity when a handle is present. Select Play track-42, then Toggle both regions to compare the static topology with its active nodes and selected edges.

The goal is complete when checkout.mmd contains a diagram derived from the executable definition. See the generated Graph API for focused graphs and activity overlays.