@aduh95/viz.js

What is @aduh95/viz.js?

@aduh95/viz.js is a JavaScript wrapper for Graphviz, a popular open-source graph visualization software. It allows you to create, manipulate, and render graphs using the DOT language directly in JavaScript environments, including Node.js and browsers.

What are @aduh95/viz.js's main functionalities?

Render DOT to SVG

This feature allows you to render a DOT string into an SVG element. The code sample demonstrates how to create a simple directed graph from node 'a' to node 'b' and append the resulting SVG to the document body.

const viz = new Viz();
viz.renderSVGElement('digraph { a -> b; }')
  .then(function(element) {
    document.body.appendChild(element);
  });

Render DOT to PNG

This feature allows you to render a DOT string into a PNG image element. The code sample shows how to create a simple directed graph and append the resulting PNG image to the document body.

const viz = new Viz();
viz.renderImageElement('digraph { a -> b; }')
  .then(function(element) {
    document.body.appendChild(element);
  });

Render DOT to plain text

This feature allows you to render a DOT string into plain text. The code sample demonstrates how to create a simple directed graph and log the resulting plain text representation to the console.

const viz = new Viz();
viz.renderString('digraph { a -> b; }')
  .then(function(result) {
    console.log(result);
  });

Other packages similar to @aduh95/viz.js

viz.js

viz.js is another JavaScript wrapper for Graphviz. It is similar to @aduh95/viz.js but is more widely used and has a larger community. It also supports rendering graphs in various formats such as SVG, PNG, and plain text.

d3-graphviz

d3-graphviz is a D3-based library for rendering Graphviz DOT files. It integrates well with the D3.js ecosystem, allowing for more complex and interactive visualizations. It is more suitable for users who are already familiar with D3.js.

graphviz-cli

graphviz-cli is a command-line interface for Graphviz. It allows you to render DOT files to various formats using the command line. It is more suitable for users who prefer working with the command line rather than a JavaScript environment.

README

Viz.js

This project builds Graphviz with Emscripten and provides a simple wrapper for using it in the browser.

See Also

Have a look at Dagre, which is not a hack.

Usage

Node.js

import Viz from "@aduh95/viz.js";
import getWorker from "@aduh95/viz.js/worker";

const worker = getWorker();
const viz = new Viz({ worker });

viz
  .renderString("digraph{1 -> 2 }")
  .then(svgString => {
    console.log(svgString);
  })
  .catch(error => {
    console.error(error);
  })
  .finally(() => {
    // If you don't terminate the worker explicitly, it will be terminated at the end of process
    worker.terminate();
  });

If you want to use it from a CommonJS script, you would need to use a dynamic imports:

async function dot2svg(dot, options = {}) {
  const Viz = await import("@aduh95/viz.js").then(m => m.default);
  const getWorker = await import("@aduh95/viz.js/worker").then(m => m.default);

  const worker = getWorker();
  const viz = new Viz({ worker });

  return viz.renderString(dot, options);
}

Browsers

You can either use the worker or the workerURL on the constructor.

import Viz from "/node_modules/@aduh95/viz.js/dist/index.mjs";

const workerURL = "/node_modules/@aduh95/viz.js/dist/render.js";

N.B.: Emscripten render.js expects to find a render.wasm on the same directory as render.js. If you are using a building tool that changes file names and/or file location, the loading would fail.

If you are using a CDN or loading the files from a different origin, most browsers will block you from spawning a cross-origin webworker. There is a workaround:

import Viz from "https://unpkg.com/@aduh95/viz.js@3.0.0-beta.2/dist/index.mjs";

const workerURL = URL.createObjectURL(
  new Blob(
    [
      "self.Module =",
      "{ locateFile: file =>",
      '"https://unpkg.com/@aduh95/viz.js@3.0.0-beta.2/dist/"',
      "+ file",
      "};", // Module.locateFile let the worker resolve the wasm file URL
      "importScripts(", // importScripts is not restricted by same-origin policy
      "Module.locateFile(", // We can use it to load the JS file
      '"render.js"',
      "));",
    ],
    { type: "application/javascript" }
  )
);

async function dot2svg(dot, options) {
  const viz = new Viz({ workerURL });

  return viz.renderString(dot, options);
}

Building From Source

To build from source, first install the Emscripten SDK. You'll also need Node.js 13+ and Yarn 2+.

On macOS:

brew install yarn binaryen emscripten automake libtool pkg-config qt

You will certainly need to tweak config files to make sure your system knows where it should find each binary.

The build process for Viz.js is split into two parts: building the Graphviz and Expat dependencies, and building the rendering script files and API.

make deps
make all -j4
make test