API Patterns

API decision flowchart: choosing the right API for your use case

Do it with an agent

Pick the right diagramkit API for [USE CASE]. Read node_modules/diagramkit/llms-full.txt for signatures. Decision rules: one-off render from a string → render(source, type, options); single file off-disk → renderFile(filePath, options); bulk directory → renderAll({ dir }); live updates during dev → watchDiagrams({ dir }); isolated worker or long-running service → createRendererRuntime(). Always await dispose() (or runtime.dispose()) when finished.

Do it manually

1) Batch Render in CI

Use this when you want rendered outputs committed or published from a docs repo.

1import { renderAll, dispose } from 'diagramkit'23const result = await renderAll({4  dir: '.',5  formats: ['svg', 'png'],6  theme: 'both',7})89console.log(result)10await dispose()

2) Watch During Authoring

Use this in local dev flows so diagram edits re-render on save.

1import { watchDiagrams, dispose } from 'diagramkit'23const stop = watchDiagrams({4  dir: '.',5  renderOptions: { formats: ['svg'] },6})78// later9await stop()10await dispose()

3) Custom Incremental Pipeline

Use this pattern when integrating into custom build tools.

1import { findDiagramFiles, filterStaleFiles, updateManifest } from 'diagramkit/utils'2import { renderDiagramFileToDisk, dispose } from 'diagramkit'34const files = findDiagramFiles('.')5const stale = filterStaleFiles(files, false, ['svg'])6for (const file of stale) await renderDiagramFileToDisk(file, { formats: ['svg'] })7updateManifest(stale, ['svg'])8await dispose()

4) Choosing the Right API

Need	Use
Render from a source string	`render()`
Render one file to memory	`renderFile()`
Render one discovered file to disk	`renderDiagramFileToDisk()`
Render a whole directory	`renderAll()`
React to file changes	`watchDiagrams()`