API Reference

Core Rendering

`ENGINE_PROFILES`

1interface DiagramEngineProfile {2  /** Runtime type: 'chromium' for browser-backed engines, 'wasm' for in-process */3  runtime: 'chromium' | 'wasm'4  /** Whether this engine needs a BrowserPool instance */5  requiresBrowserPool: boolean6  /** Whether renders must be serialized within a type lane */7  serializedWithinLane: boolean8  /** Ordering priority for lane scheduling (lower runs first) */9  laneOrder: number10}1112const ENGINE_PROFILES: Record<DiagramType, DiagramEngineProfile>

Static engine metadata used by the render pipeline and CLI planning.

`getEngineProfile(type)`

1function getEngineProfile(type: DiagramType): DiagramEngineProfile

Returns engine metadata for a specific diagram type.

`render(source, type, options?)`

Render a diagram from a source string.

1function render(2  source: string,3  type: DiagramType,4  options?: RenderOptions,5): Promise<RenderResult>

Parameter	Type	Required	Description
`source`	`string`	Yes	Diagram source content
`type`	`DiagramType`	Yes	Engine to use
`options`	`RenderOptions`	No	Rendering config

Behavior: Acquires the browser pool for browser-backed engines. For theme: 'both', renders both variants. Applies postProcessDarkSvg() to Mermaid dark SVGs when contrastOptimize is true. Converts to raster via sharp for non-SVG formats.

`renderFile(filePath, options?)`

Render a file from disk. Type inferred from extension.

1function renderFile(2  filePath: string,3  options?: RenderOptions,4): Promise<RenderResult>

`renderAll(options?)`

Batch render all diagrams in a directory tree. Writes to .diagramkit/ folders.

1function renderAll(options?: BatchOptions): Promise<RenderAllResult>

Returns RenderAllResult with rendered, skipped, failed, failedDetails, and optional metrics.

Steps: discover files, filter by type, check manifest, render stale files, update manifest, clean orphans.

`renderDiagramFileToDisk(file, options?)`

Render a single file and write output to disk. Returns written filenames.

1function renderDiagramFileToDisk(2  file: DiagramFile,3  options?: RenderOptions & { config?: DiagramkitConfig; outDir?: string; formats?: OutputFormat[] },4): Promise<string[]>

`watchDiagrams(options)`

Watch for changes and re-render. Returns cleanup function.

1function watchDiagrams(options: WatchOptions): () => Promise<void>

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

Browser Lifecycle

`warmup()`

1function warmup(): Promise<void>

Pre-warm the browser pool. Optional — launches automatically on first render.

`dispose()`

1function dispose(): Promise<void>

Close browser pool and release resources. Safe to call multiple times.

`createRendererRuntime()`

1function createRendererRuntime(): RendererRuntime

Creates an isolated runtime with its own BrowserPool. Use this when you need lifecycle isolation from the default singleton runtime.

Do not mix runtime.dispose() with the top-level dispose() for the same work unit. Runtime methods manage their own pool; the top-level API manages the shared singleton pool.

`DiagramkitError`

1class DiagramkitError extends Error {2  code: DiagramkitErrorCode3}

Typed error class used for user-facing and programmatic failures.

File Discovery

Import these utilities from diagramkit/utils, not from the main diagramkit entry.

1import { findDiagramFiles, filterByType } from 'diagramkit/utils'

`findDiagramFiles(dir, config?)`

1function findDiagramFiles(2  dir: string,3  config?: Partial<DiagramkitConfig>,4): DiagramFile[]

Recursively find all diagram files. Skips hidden dirs and node_modules.

`filterByType(files, type, config?)`

1function filterByType(2  files: DiagramFile[],3  type: DiagramType,4  config?: Partial<DiagramkitConfig>,5): DiagramFile[]

Manifest

`filterStaleFiles(files, force, formats?, config?, theme?)`

1function filterStaleFiles(2  files: DiagramFile[],3  force: boolean,4  formats?: OutputFormat[],5  config?: Partial<DiagramkitConfig>,6  theme?: Theme,7): StaleFile[]

Filter to files needing re-render. Caches manifests per directory.

`planStaleFiles(files, force, formats?, config?, theme?)`

1function planStaleFiles(2  files: DiagramFile[],3  force: boolean,4  formats?: OutputFormat[],5  config?: Partial<DiagramkitConfig>,6  theme?: Theme,7): StalePlanEntry[]

Returns detailed staleness reasons per file without rendering.

`isStale(file, formats?, config?, theme?, manifest?)`

1function isStale(2  file: DiagramFile,3  formats?: OutputFormat[],4  config?: Partial<DiagramkitConfig>,5  theme?: Theme,6  manifest?: Manifest,7): boolean

Returns true if: no manifest entry, hash changed, format changed, outputs missing, or manifest disabled.

`readManifest(sourceDir, config?)`

1function readManifest(2  sourceDir: string,3  config?: Partial<DiagramkitConfig>,4): Manifest

`getDiagramsDir(sourceDir, config?)`

1function getDiagramsDir(sourceDir: string, config?: Partial<DiagramkitConfig>): string

`ensureDiagramsDir(sourceDir, config?)`

1function ensureDiagramsDir(sourceDir: string, config?: Partial<DiagramkitConfig>): string

Like getDiagramsDir but creates the directory if missing.

Extension Utilities

`getExtensionMap(overrides?)`

1function getExtensionMap(overrides?: Record<string, DiagramType>): Record<string, DiagramType>

`getDiagramType(filename, map?)`

1function getDiagramType(filename: string, map?: Record<string, DiagramType>): DiagramType | null

Longest-match-first resolution.

`getMatchedExtension(filename, map?)`

1function getMatchedExtension(filename: string, map?: Record<string, DiagramType>): string | null

`getAllExtensions(map?)`

1function getAllExtensions(map?: Record<string, DiagramType>): string[]

`getExtensionsForType(type, map?)`

1function getExtensionsForType(type: DiagramType, map?: Record<string, DiagramType>): string[]

Configuration

`getDefaultConfig()`

1function getDefaultConfig(): DiagramkitConfig

`loadConfig(overrides?, dir?, configFile?, options?)`

1function loadConfig(2  overrides?: Partial<DiagramkitConfig>,3  dir?: string,4  configFile?: string,5  options?: { strict?: boolean; warn?: (message: string) => void },6): DiagramkitConfig

Merge order: defaults, global, env vars, local (or explicit configFile), overrides.

`getFileOverrides(filePath, config?, rootDir?)`

1function getFileOverrides(2  filePath: string,3  config?: Partial<DiagramkitConfig>,4  rootDir?: string,5): FileOverride | undefined

Resolve per-file overrides from the overrides config. Matches against exact filenames, relative paths, and glob patterns. Returns the merged override for the file, or undefined if no overrides match.

`defineConfig(config)`

1function defineConfig(config: Partial<DiagramkitConfig>): Partial<DiagramkitConfig>

Identity helper for TypeScript config file autocomplete. Returns the input unchanged but provides type checking in diagramkit.config.ts files.

`defaultMermaidDarkTheme`

1const defaultMermaidDarkTheme: Record<string, string>

SVG-to-Raster Conversion

`convertSvg(svg, options)`

1function convertSvg(2  svg: Buffer | string,3  options: ConvertOptions,4): Promise<Buffer>

Also available from diagramkit/convert.

Color Utilities

`postProcessDarkSvg(svg)`

1function postProcessDarkSvg(svg: string): string

WCAG contrast optimization for dark SVGs. Exported from diagramkit/utils and diagramkit/color.

Output Utilities

`atomicWrite(path, content)`

1function atomicWrite(path: string, content: Buffer): void

Write via .tmp + rename to prevent partial files.

`stripDiagramExtension(filename, map?)`

1function stripDiagramExtension(filename: string, map?: Record<string, DiagramType>): string

Removes the detected diagram extension from the filename.

Utilities (Advanced)

These functions are available from diagramkit/utils for advanced use cases such as custom build pipelines.

`writeManifest(sourceDir, manifest, config?)`

1function writeManifest(2  sourceDir: string,3  manifest: Manifest,4  config?: Partial<DiagramkitConfig>,5): void

Write manifest atomically (.tmp + rename) to prevent corruption on crash.

`hashFile(filePath)`

1function hashFile(filePath: string): string

Compute SHA-256 content hash of a file. Returns a sha256: prefixed hex string (first 16 chars).

`renderGraphviz(source, options?)`

1function renderGraphviz(2  source: string,3  options?: { theme?: Theme; contrastOptimize?: boolean },4): Promise<{ lightSvg?: string; darkSvg?: string }>

Low-level Graphviz renderer used by the unified engine pipeline.

`cleanOrphans(files, config?, roots?)`

1function cleanOrphans(2  files: DiagramFile[],3  config?: Partial<DiagramkitConfig>,4  roots?: string[],5): void

Remove orphaned outputs and manifest entries for diagram sources that no longer exist.

`updateManifest(files, formats?, config?, theme?)`

1function updateManifest(2  files: RenderableFile[],3  formats?: OutputFormat[],4  config?: Partial<DiagramkitConfig>,5  theme?: Theme,6): void

Update manifests after successful renders. Groups files by directory and merges formats with existing entries.

`writeRenderResult(name, outDir, result, naming?)`

1function writeRenderResult(2  name: string,3  outDir: string,4  result: RenderResult,5  naming?: OutputNamingOptions,6): string[]

Write whichever variants were returned by the renderer. Returns an array of written filenames.

`getExpectedOutputNamesMulti(name, formats, theme?, naming?)`

1function getExpectedOutputNamesMulti(2  name: string,3  formats: OutputFormat[],4  theme?: Theme,5  naming?: OutputNamingOptions,6): string[]

Get expected output names across multiple formats and theme variants.

`getExpectedOutputNames(name, format?, theme?, naming?)`

1function getExpectedOutputNames(2  name: string,3  format?: OutputFormat,4  theme?: Theme,5  naming?: OutputNamingOptions,6): string[]

Get expected output names for a single format and theme.

`getOutputFileName(name, variant, format?, naming?)`

1function getOutputFileName(2  name: string,3  variant: 'light' | 'dark',4  format?: OutputFormat,5  naming?: OutputNamingOptions,6): string

Get the output filename for a specific variant and format. Pattern: {prefix}{name}{suffix}-{variant}.{format}.

`getOutputVariants(theme?)`

1function getOutputVariants(theme?: Theme): ('light' | 'dark')[]

Get the output variants for a given theme. Returns ['light'], ['dark'], or ['light', 'dark'].

SVG Validation

Import these functions from diagramkit/utils or diagramkit/validate. They are also surfaced through the CLI as diagramkit validate and run automatically after every diagramkit render.

1import {2  validateSvg,3  validateSvgFile,4  validateSvgDirectory,5  formatValidationResult,6} from 'diagramkit/utils'

`validateSvg(svg, filePath?, options?)`

1function validateSvg(2  svg: string,3  filePath?: string,4  options?: SvgValidateOptions,5): SvgValidationResult

Structural + WCAG 2.2 AA contrast validation of an SVG string. Returns issues with codes (MISSING_SVG_TAG, LOW_CONTRAST_TEXT, EXTERNAL_RESOURCE, …), severity, message, and a remediation suggestion.

`validateSvgFile(filePath, options?)`

1function validateSvgFile(filePath: string, options?: SvgValidateOptions): SvgValidationResult

`validateSvgDirectory(dir, options?)`

1function validateSvgDirectory(2  dir: string,3  options?: { recursive?: boolean } & SvgValidateOptions,4): SvgValidationResult[]

`formatValidationResult(result)`

1function formatValidationResult(result: SvgValidationResult): string

Format a SvgValidationResult into the human-readable lines used by diagramkit validate.

See Types for SvgIssue, SvgIssueCode, SvgValidationResult, and SvgValidateOptions shapes.

Subpath Exports

Import	Content
`diagramkit`	Main API
`diagramkit/utils`	Discovery, manifest, extensions, output, color, validation
`diagramkit/color`	Color utilities (contrast, WCAG ratios)
`diagramkit/convert`	SVG-to-raster conversion
`diagramkit/validate`	SVG structural + WCAG contrast validation