graphviz-cli

Command-line tool and API for generating graph images from Graphviz source scripts.

Features:

• Runs in pure JavaScript. Except for the png output.
• No need to install the native Graphviz package.
• Most output formats of the native Graphviz (inluding svg and png) available.
• TypeScript type declarations (typings) for the API.
• A lot faster then calling dot as a separate process.

Uses @aduh95/viz.js to render Graphviz scripts in pure JavaScript by WASM. Uses node-canvas for the optional png output.

Related tools:

• graphviz-builder - generates the source script for Graphviz consumable by this tool
• graphviz-webcomponent - WebComponent for web browsers to display graph images from the source scripts in HTML pages on-the-fly

Synopsis

graphviz -Tsvg -ohello.svg hello.dot

import { renderGraphFromSource } from 'graphviz-cli'
// Render a string with the graph script to a string with the SVG output.
const svg = await renderGraphFromSource({ input: 'graph G { ... }' }, { format: 'svg' })
// Render a file with a graph script to a file with the PNG output.
await renderGraphFromSource({ name: 'hello.dot' }, { format: 'png', name: 'hello.png' })

Installation

Make sure that you have installed Node.js 14.8 or newer.

If you want to use the command-line tool, install this package globally using your favourite package manager (NPM, Yarn or PNPM):

npm i -g graphviz-cli
yarn global add graphviz-cli
pnpm i -g graphviz-cli

If you want to use this package programmatically, install it locally using your favourite package manager. Add -D on the command line if you need the tool only to build you package:

npm i graphviz-cli
yarn add graphviz-cli
pnpm i graphviz-cli

If you want to render graphs to png, install the node-canvas module in addition. Add -g/global or -D arguments according to you choice above:

npm i canvas
yarn add canvas
pnpm i canvas

Starting from the version 2.0.0, node-canvas is not a peer dependency any more, because NPM installs the peer dependencies automatically, making them not optional any more.

Command-line

Command-line parameters are the same as for the dot tool from the Graphviz package, as long as they are implemented, of course.

$ graphviz -?

Generates graph images from Graphviz source scripts.

Usage: graphviz [-Vvy?] [-(KTon)<value>] <dot files>

Options:
  -Tv           - set output format to 'v'
  -Kv           - set layout engine to 'v' (overrides source script)
  -ofile        - write output to 'file'
  -O            - automatically generate an output filename based on the input
                  filename with a .'format' appended. (Causes all -ofile
                  options to be ignored.)
  -y            - invert y coordinate in output
  -n[v]         - no layout mode 'v' (=1)
  -v            - enable verbose mode
  -V            - print version and exit
  -?            - print usage and exit

Examples:
  graphviz -Tsvg -O diagrams/*.dot
  graphviz -Tpng -Kneato -odiagram.png diagram.dot

API

renderGraphFromSource(source: object, options: object): Promise<string | Buffer>

Renders a graph script to a specified output. If the output format is binary (png, for example), the Promise will contain Buffer instead of string.

import { renderGraphFromSource } from 'graphviz-cli'
// Render a string with the graph script to a string with the SVG output.
const svg = await renderGraphFromSource({ input: 'graph G { ... }' }, { format: 'svg' })
// Render a file with a graph script to a file with the PNG output.
await renderGraphFromSource({ name: 'hello.dot' }, { format: 'png', name: 'hello.png' })

Source properties:

| name | type | description | |---------|----------|---------------------------------| | name | string | file name with the graph script | | input | string | graph script |

If neither name nor input are provided, or the whole source parameter is omitted, the graph script will be read from the standard input.

Available options:

| name | type | description | |-----------|-----------|---------------------------------------------| | name | string | file name for the generated graph output | | engine | string | type of the layout to use for the graph rendering (circo, dot, fdp, neato, osage, twopi, default is dot) | | format | string | type of the output for the rendered graph (svg, png, dot, xdot, plain, plain-ext, ps, ps2, json, json0, canon, default is dot) | | yInvert | boolean | invert the y-coordinate in the graph output | | nop | number | no layout mode 'v' (0 or 1) |

If name is not provided the output will be available only in the Promise. If the format png is specified, the NPM module node-canvas has to be installed, which is required as a peer-dependency of this package.

engines

List of available graph layout engines: circo, dot, fdp, neato, osage, twopi.

formats

List of available graph outout formats: svg, png, dot, xdot, plain, plain-ext, ps, ps2, json, json0, canon.

License

Copyright (c) 2020-2022 Ferdinand Prantl

Licensed under the MIT license.