Skip to main content
On this page

Watch Mode

Watch mode event loop: monitor, debounce, re-render, update manifest

Watch mode monitors diagram source files and re-renders them on save. It uses chokidar for file watching.

CLI Usage

Shell
diagramkit render . --watch

This performs an initial full render, then watches for changes:

Text
Rendered 5/5 diagrams to svgWatching for diagram changes...Changed: docs/architecture.mermaid  Re-rendered: docs/architecture.mermaid

Press Ctrl+C to stop.

Combine with Other Flags

Shell
diagramkit render . --watch --format pngdiagramkit render . --watch --type mermaiddiagramkit render . --watch --format png --scale 3diagramkit render . --watch --no-contrast

JavaScript API

TypeScript
import { renderAll, watchDiagrams, dispose } from 'diagramkit'// Initial renderawait renderAll({ dir: './content' })// Start watchingconst stop = watchDiagrams({  dir: './content',  renderOptions: { format: 'svg', theme: 'both' },  onChange: (file) => console.log(`Updated: ${file}`),})// Stop watching when doneprocess.on('SIGINT', async () => {  await stop()  await dispose()})

Watched File Types

All supported extensions are monitored:

**/*.mermaid, **/*.mmd, **/*.mmdc, **/*.excalidraw, **/*.drawio, **/*.drawio.xml, **/*.dio, **/*.dot, **/*.gv, **/*.graphviz

Ignored: node_modules/, hidden directories (.git/, .diagramkit/, etc.), output directory.

Advanced Watch Options

Option Type Default Description
debounceMs number 200 Debounce time for file events (ms)
usePolling boolean false Use polling mode (recommended for Docker/network volumes)
pollingInterval number — Polling interval in ms when usePolling is true
TypeScript
const stop = watchDiagrams({  dir: './content',  usePolling: true,  pollingInterval: 500,  debounceMs: 300,})

Behavior

  • Safe rendering — only the changed file re-renders. If rendering fails (e.g. syntax error), existing outputs are preserved.
  • Manifest updates — the manifest updates after each successful re-render, keeping incremental tracking accurate.
  • Browser stays warm — the browser pool remains alive during watch mode for fast subsequent renders.

Dev Server Integration

Run diagramkit alongside your dev server in a separate terminal:

Shell
# Terminal 1npm run dev# Terminal 2npx diagramkit render . --watch

The onChange callback in the JS API can trigger hot-reload:

TypeScript
const stop = watchDiagrams({  dir: './content',  onChange: () => notifyDevServer(),})