ts-graphviz

Common errors

• Error: spawn dot ENOENT

  cause The Graphviz `dot` command-line tool is not found in the system's PATH, which is required by the `render` function.
  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.

• TypeError: (0 , ts_graphviz_1.digraph) is not a function

  cause Attempting to use CommonJS `require()` syntax or an incorrect import path for `ts-graphviz`, which is primarily an ESM package.
  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`).

• TS2307: Cannot find module 'ts-graphviz' or its corresponding type declarations.

  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).
  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.

Warnings

• breaking ts-graphviz requires Node.js version 20 or higher. Running on older Node.js versions may lead to unexpected errors or incompatibility issues.
  Fix: Upgrade your Node.js environment to version 20 or newer. Consider using a version manager like `nvm` (`nvm install 20 && nvm use 20`).
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• npm install ts-graphviz npm
• yarn add ts-graphviz yarn
• pnpm add ts-graphviz pnpm

Imports

• digraph
  wrong:

  const { digraph } = require('ts-graphviz');

  correct:

  import { digraph } from '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
  wrong:

  import node from 'ts-graphviz/node';

  correct:

  import { node } from 'ts-graphviz';

  Common graph elements like `node` and `edge` are named exports directly from the main package, not from sub-paths.
• render
  wrong:

  import { render } from '@ts-graphviz/adapter';

  correct:

  import { render } from 'ts-graphviz';

  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.

Quickstart

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();