ts-graphviz
    Preparing search index...

    ts-graphviz

    Main CodeQL License: MIT All Contributors

    OpenSSF Best Practices OpenSSF Scorecard Tidelift

    npm version node version deno version npm

    ts-graphviz

    Graphviz library for TypeScript.

    🔗

    GitHub npm Reference Ask DeepWiki

    Sponsor OpenCollective

    format: Biome test: Vitest build: Vite


    ts-graphviz is a comprehensive TypeScript library that provides tools for creating, manipulating, and rendering Graphviz graph descriptions. It offers a type-safe, object-oriented approach to working with the DOT language, which is used by Graphviz for defining graph visualizations.

    ts-graphviz offers several distinctive features that make it valuable for TypeScript/JavaScript developers working with graph visualizations:

    • TypeScript-friendly API
      • Provides fully typed models for the DOT language with type definitions for graph attributes.
    • Flexible Programming Paradigms
      • Supports both object-oriented and declarative approaches.
    • Multi-level API
      • Offers high-level model APIs and low-level AST manipulation.
    • Modular Design
      • Structured as separate packages for specific functionalities.
    • Cross-platform Support
      • Works in Node.js and Deno environments
    • Extensible
      • Allows extending the type system for custom graph visualization solutions.

    ts-graphviz is designed to make it easier for TypeScript and JavaScript developers to work with Graphviz by providing a type-safe, object-oriented API that abstracts away the complexities of the DOT language. It allows developers to create and manipulate graphs programmatically, making it suitable for both small-scale projects and large applications. It is particularly useful for applications that require dynamic graph generation, such as data visualization tools, network analysis, and more.

    This package can then be installed using a package manager.

    # npm
    $ npm install -S ts-graphviz
    # or yarn
    $ yarn add ts-graphviz
    # or pnpm
    $ pnpm add ts-graphviz

    Note Want to try before installing? Check out Runkit to see how it works.

    Deno v1.28 and above supports npm.

    You can install and use the package by specifying the following:

    import { toDot } from 'npm:ts-graphviz';
    

    ts-graphviz provides two main approaches to create graph visualizations:

    Create graphs using object-oriented programming with classes:

    import { attribute as _, Digraph, Subgraph, Node, Edge, toDot } from 'ts-graphviz';

    // Create a directed graph
    const graph = new Digraph();

    // Create nodes
    const node1 = new Node('node1', { color: 'red' });
    const node2 = new Node('node2', { color: 'blue' });

    // Create an edge between the nodes
    const edge = new Edge([node1, node2], { label: 'Edge Label' });

    // Add elements to the graph
    graph.addNode(node1);
    graph.addNode(node2);
    graph.addEdge(edge);

    // Convert to DOT language
    const dot = toDot(graph);

    // Convert to DOT language
    const dot = toDot(G);
    // digraph {
    // "node1" [
    // color = "red",
    // ];
    // "node2" [
    // color = "blue",
    // ];
    // "node1" -> "node2" [
    // label = "Edge Label",
    // ];
    // }

    Create graphs using a declarative approach with a factory function:


    ```ts
    import { attribute as _, digraph, toDot } from 'ts-graphviz';

    // Create a directed graph using the factory function
    const graph = digraph('G', (g) => {
    // Create nodes within the graph context
    const a = g.node('a');
    const b = g.node('b');

    // Create an edge between nodes
    g.edge([a, b], { label: 'connects to' });

    // Create a subgraph with its own nodes and edges
    g.subgraph('A', (sg) => {
    const c = sg.node('c');
    const d = sg.node('d');
    sg.edge([c, d]);
    });
    });

    // Convert to DOT language
    const dot = toDot(graph);
    // digraph G {
    // "a";
    // "b";
    // "a" -> "b" [
    // label = "connects to",
    // ];
    // subgraph "A" {
    // "c";
    // "d";
    // "c" -> "d";
    // }
    // }

    The @ts-graphviz/react package provides React components for creating Graphviz graphs declaratively with JSX:

    import { Digraph, Node, Edge, renderToDot } from '@ts-graphviz/react';

    // Define reusable components
    const UserCard = ({ id, name, role }) => (
    <Node
    id={id}
    shape="record"
    label={
    <dot:table border="0" cellborder="1" cellspacing="0">
    <dot:tr>
    <dot:td bgcolor="lightblue">
    <dot:b>{name}</dot:b>
    </dot:td>
    </dot:tr>
    <dot:tr>
    <dot:td>{role}</dot:td>
    </dot:tr>
    </dot:table>
    }
    />
    );

    const StatusBadge = ({ status }) => (
    <dot:font color={status === 'active' ? 'green' : 'red'}>
    <dot:b>{status.toUpperCase()}</dot:b>
    </dot:font>
    );

    // Compose the graph
    const TeamStructure = () => (
    <Digraph rankdir="TB">
    <UserCard id="alice" name="Alice Smith" role="Team Lead" />
    <UserCard id="bob" name="Bob Johnson" role="Developer" />
    <UserCard id="carol" name="Carol Davis" role="Designer" />

    <Node
    id="project"
    label={
    <>
    <dot:b>Project Alpha</dot:b><dot:br/>
    Status: <StatusBadge status="active" />
    </>
    }
    shape="box"
    style="rounded,filled"
    fillcolor="lightyellow"
    />

    <Edge targets={["alice", "bob"]} label="manages" />
    <Edge targets={["alice", "carol"]} label="manages" />
    <Edge targets={["project", "alice"]} label="assigned to" style="dashed" />
    </Digraph>
    );

    // Render to DOT
    const dot = await renderToDot(<TeamStructure />);
    Tip

    See the @ts-graphviz/react documentation for comprehensive examples and API reference.

    More detailed documentation and examples can be found in the following resources:

    • API Reference
      • See the API Reference for detailed documentation on how to use the library.
    • DeepWiki
      • See the AI generated documentation for more information.
      • And ask questions about the library.
    • Website
      • The official website for ts-graphviz.

    See ARCHITECTURE.md for more details.

    See SECURITY.md for more details.

    The ts-graphviz repository is structured as a monorepo containing several packages, each with a specific responsibility:

    Package Purpose
    ts-graphviz Main entry point providing a high-level API for most users
    @ts-graphviz/core Core object models for graph manipulation
    @ts-graphviz/ast Parser and AST (Abstract Syntax Tree) handling for DOT language
    @ts-graphviz/adapter Platform-specific implementations for rendering graphs
    @ts-graphviz/common Shared types and utilities used across packages
    @ts-graphviz/react React components for creating and rendering Graphviz graphs
    Tip

    Dependency graph Packages' Dependency graph

    The following diagram illustrates how data flows through the ts-graphviz system, from graph creation to final rendering:

    Data flow

    1. Creation Phase: Users create graph models through object-oriented API, React components, or parsing DOT strings
    2. Processing Phase: Models are converted to AST and then to DOT language strings
    3. Rendering Phase: Platform-specific adapters convert DOT strings to visual output formats
      1. The adapters handle platform-specific operations, such as executing the Graphviz dot command in Node.js/Deno, while maintaining a consistent API across environments.
    Tip

    Rendering in the browser is not directly supported by this library, but you can use other libraries like @hpcc-js/wasm-graphviz to achieve rendering in the browser.

    • Model -> AST: Converts object model to abstract syntax tree
    • AST -> DOT: Generates DOT language string from AST
    • DOT -> AST: Parses DOT language into AST
    • AST -> Model: Converts AST back to object model
    • DOT -> Output: Uses adapters to render visual outputs

    The toDot() function from the ts-graphviz package is a composite of fromModel() and stringify(), while the fromDot() function is a composite of parse() and toModel().

    Note

    Let us know that you're using ts-graphviz on GitHub Discussions 🙏

    Related projects can be found at ts-graphviz GitHub Organization.

    The TypeScript/JavaScript ecosystem provides a variety of OSS with the goal of making Graphviz more connected and easier to use.

    Thanks goes to these wonderful people (emoji key):

    Yuki Yamazaki
    Yuki Yamazaki

    💻 ⚠️ 📖 🤔
    LaySent
    LaySent

    🐛 ⚠️
    elasticdotventures
    elasticdotventures

    📖
    Christian Murphy
    Christian Murphy

    💻 🤔 📖
    Artem
    Artem

    🐛
    fredericohpandolfo
    fredericohpandolfo

    🐛
    diegoquinteiro
    diegoquinteiro

    🐛
    robross0606
    robross0606

    🤔
    Blake Regalia
    Blake Regalia

    🐛
    bigbug
    bigbug

    💬
    mrwk
    mrwk

    💬
    svdvonde
    svdvonde

    💬
    Adam
    Adam

    💬
    Trevor Scheer
    Trevor Scheer

    ️️️️♿️
    Prem Pillai
    Prem Pillai

    🐛
    nagasawaryoya
    nagasawaryoya

    💻 ⚠️
    YukiSasaki
    YukiSasaki

    💻 ⚠️
    Madd0g
    Madd0g

    🐛
    j4k0xb
    j4k0xb

    🐛
    HKrogstie
    HKrogstie

    🐛
    Nils K
    Nils K

    🐛
    hao2013
    hao2013

    🚧 👀
    Walter Rafelsberger
    Walter Rafelsberger

    💬
    grsjst
    grsjst

    🐛
    Steve
    Steve

    🐛

    This project follows the all-contributors specification. Contributions of any kind welcome!

    The easiest way to contribute is to use the library and star repository.

    Feel free to ask questions on GitHub Discussions.

    Please register at GitHub Issues.

    See CONTRIBUTING.md.

    Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Become a sponsor

    OpenCollective Sponsors

    Thank you to all our backers! 🙏 Become a backer

    OpenCollective Backers

    Please support ts-graphviz on Open Collective or GitHub Sponsors.

    Note Even just a dollar is enough motivation to develop 😊

    Available as part of the Tidelift Subscription.

    The maintainers of ts-graphviz and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open-source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use.

    Learn more.

    This software is released under the MIT License, see LICENSE.