{"id":12175,"library":"ts-graphviz","title":"ts-graphviz","description":"ts-graphviz is a TypeScript-first library designed to programmatically construct and render Graphviz DOT language graphs. It provides a type-safe API for defining complex graph structures, including nodes, edges, and subgraphs, with full attribute support. The current stable version is 3.0.7, which is part of a monorepo that sees regular patch and minor releases across its constituent packages like `@ts-graphviz/core`, `@ts-graphviz/react`, and `@ts-graphviz/adapter`. This library differentiates itself by leveraging TypeScript's strong typing to prevent common Graphviz syntax errors at compile-time and offering a clean, object-oriented API for graph construction, making it suitable for modern Node.js and browser environments, especially when integrated with frameworks like React.","status":"active","version":"3.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/ts-graphviz/ts-graphviz","tags":["javascript","graphviz","dot","typescript"],"install":[{"cmd":"npm install ts-graphviz","lang":"bash","label":"npm"},{"cmd":"yarn add ts-graphviz","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-graphviz","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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.","package":"Graphviz CLI tools","optional":false}],"imports":[{"note":"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.","wrong":"const { digraph } = require('ts-graphviz');","symbol":"digraph","correct":"import { digraph } from 'ts-graphviz';"},{"note":"Common graph elements like `node` and `edge` are named exports directly from the main package, not from sub-paths.","wrong":"import node from 'ts-graphviz/node';","symbol":"node","correct":"import { node } from 'ts-graphviz';"},{"note":"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`.","wrong":"import { render } from '@ts-graphviz/adapter';","symbol":"render","correct":"import { render } from 'ts-graphviz';"},{"note":"Used to serialize a constructed graph object into a Graphviz DOT language string without needing the external CLI tools.","symbol":"toDot","correct":"import { toDot } from 'ts-graphviz';"}],"quickstart":{"code":"import { digraph, node, edge, toDot, render } from 'ts-graphviz';\nimport { writeFile } from 'fs/promises';\n\nasync function generateGraphImage() {\n  const G = digraph('MyGraph', (g) => {\n    const start = node('start', { shape: 'Mdiamond', label: 'Start' });\n    const processA = node('processA', { label: 'Process A' });\n    const processB = node('processB', { label: 'Process B' });\n    const end = node('end', { shape: 'Msquare', label: 'End' });\n\n    edge([start, processA], { label: 'Init' });\n    edge([processA, processB], { label: 'Data Transfer' });\n    edge([processB, end], { label: 'Completion', color: 'green' });\n\n    g.subgraph('cluster_steps', (c) => {\n      c.label = 'Workflow Steps';\n      c.style = 'filled';\n      c.color = 'lightgrey';\n      c.addNode(processA, processB);\n    });\n    g.addNode(start, end);\n  });\n\n  const dotString = toDot(G);\n  console.log('Generated DOT string:\\n', dotString);\n\n  try {\n    // Ensure Graphviz CLI 'dot' is installed and available in your system's PATH.\n    // e.g., on macOS: `brew install graphviz`\n    // e.g., on Ubuntu: `sudo apt-get install graphviz`\n    const imageBuffer = await render(G, { format: 'png' });\n    await writeFile('workflow_graph.png', imageBuffer);\n    console.log('Graph image successfully generated at workflow_graph.png');\n  } catch (error) {\n    console.error('Error rendering graph. Is Graphviz CLI installed and in PATH?', error);\n    throw error;\n  }\n}\n\ngenerateGraphImage();\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or newer. Consider using a version manager like `nvm` (`nvm install 20 && nvm use 20`).","message":"ts-graphviz requires Node.js version 20 or higher. Running on older Node.js versions may lead to unexpected errors or incompatibility issues.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Install Graphviz CLI tools on your operating system. For example, `brew install graphviz` on macOS, or `sudo apt-get install graphviz` on Debian/Ubuntu.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update 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.","message":"Version 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.","severity":"breaking","affected_versions":"<3.0.6"},{"fix":"Ensure 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.","message":"When 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.","severity":"gotcha","affected_versions":"<0.12.0 of @ts-graphviz/react"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install 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.","cause":"The Graphviz `dot` command-line tool is not found in the system's PATH, which is required by the `render` function.","error":"Error: spawn dot ENOENT"},{"fix":"Ensure 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`).","cause":"Attempting to use CommonJS `require()` syntax or an incorrect import path for `ts-graphviz`, which is primarily an ESM package.","error":"TypeError: (0 , ts_graphviz_1.digraph) is not a function"},{"fix":"Install 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.","cause":"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).","error":"TS2307: Cannot find module 'ts-graphviz' or its corresponding type declarations."}],"ecosystem":"npm"}