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-graphvizNote 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
Packages' Dependency graph
The following diagram illustrates how data flows through the ts-graphviz system, from graph creation to final rendering:
- Creation Phase: Users create graph models through object-oriented API, React components, or parsing DOT strings
- Processing Phase: Models are converted to AST and then to DOT language strings
- Rendering Phase: Platform-specific adapters convert DOT strings to visual output formats
- 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):
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
Thank you to all our backers! 🙏 Become a backer
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.
This software is released under the MIT License, see LICENSE.
