Use the React component directly

The Astro integration is a thin layer. The diagram itself is a React component, DiagramView, that takes compiled JSON and nothing else. If you do not use Astro, you can compile your diagrams yourself and render them in any React app.

1. Compile at build time

import { writeFileSync } from 'node:fs'
import { formatDiagnostic, loadProject } from '@the-package-labs/idocs-core/node'

const { diagrams, diagnostics } = loadProject(process.cwd()) // reads ./diagrams/*/diagram.yaml

for (const d of diagnostics) console.error(formatDiagnostic(d))
if (diagnostics.some((d) => d.severity === 'error')) process.exit(1)

writeFileSync('src/diagrams.json', JSON.stringify(diagrams))

loadProject(root, dir = 'diagrams') returns { diagrams, diagnostics, watch }. diagrams maps a diagram’s name to its CompiledDiagram, which is plain JSON: no functions, classes, Maps or Dates. That is what lets it cross a server and client boundary.

2. Render it

import { DiagramView } from '@the-package-labs/idocs-react'
import '@the-package-labs/idocs-react/styles.css'
import diagrams from './diagrams.json'

export function Architecture() {
  return <DiagramView diagram={diagrams.checkout} scenario="place-order" />
}

Import the stylesheet once. Install @the-package-labs/idocs-react with react and react-dom 19 or later.

Props

Prop	Type	Meaning
`diagram`	`CompiledDiagram`	Required. One entry of `diagrams`.
`view`	string	The view to show first. Defaults to the diagram’s `defaults.view`.
`scenario`	string	The scenario to select first. Defaults to the diagram’s `defaults.scenario`.
`mode`	`'flow' \| 'sequence' \| 'story'`	How the scenario is shown. Defaults to the scenario’s `mode`, then the diagram’s `defaults.mode`.
`autoplay`	boolean	Play the scenario selected first once it is laid out. Defaults to the diagram’s `defaults.autoplay`.
`maxHeight`	number	The tallest the canvas may grow, in pixels. Default 780.
`showTitle`	boolean	Show the diagram’s title.
`showDescription`	boolean	Show its description.
`hash`	boolean	Keep the scenario, step and opened nodes in the URL hash. Default `true`.
`sidebar`	boolean	Start with the panel over the picture (outline and views) open. Default: the diagram’s `defaults.sidebar`, else open when there is another view to choose, and the widget is wider than about 640 px.
`subtitles`	boolean	Show the step’s title and description on the bar while the scenario plays. Defaults to the diagram’s `defaults.subtitles`, then `true`.
`className`	string	An extra class on the root element.

Things to know

Heights are measured in the browser. The component renders each card offscreen at its fixed width, measures it, and lays the diagram out. Until then it shows a placeholder. In server rendering you get the placeholder, and the diagram appears after hydration.
Load it lazily. The layout engine is large. Render the component in a lazily loaded chunk, or only when it scrolls into view, as the Astro integration does with client:visible.
Fonts. Diagrams use --idocs-sans and --idocs-mono. Load IBM Plex or set those tokens. When web fonts finish loading, the component measures again.
Theme. The component follows data-theme="dark" on the page’s root element (<html data-theme="dark">), or the system preference when the attribute is absent. See theming.

Other exports

@the-package-labs/idocs-react also exports the building blocks, if you want to compose your own view: NodeCard, Icon, IconTile and SequenceView. See packages.