ts-graphviz
What is ts-graphviz? 🎯
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.
Key Features ✨
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.
Why ts-graphviz? 🤔
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.
Getting Started 🚀
Installation 💽
Node.js
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 🦕
Deno v1.28 and above supports npm.
You can install and use the package by specifying the following:
import { toDot } from 'npm:ts-graphviz';
Basic Usage 📖
ts-graphviz provides two main approaches to create graph visualizations:
Object-Oriented API
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",
// ];
// }
Declarative API (Factory Function)
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";
// }
// }
Declarative API (React Component)
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.
Useful Links 🔗
Documentation 📖
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.
Architecture 🏛
See ARCHITECTURE.md for more details.
Security 🛡️
See SECURITY.md for more details.
Package Structure 📦
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
Data Flow and Processing Pipeline 🔄
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.
Key Data Transformations:
- 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().
Who's using ts-graphviz 📜
[!NOTE] Let us know that you're using
ts-graphvizon GitHub Discussions 🙏
Related Projects 💫
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.
Contributors 👥
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
How to Contribute 💪
The easiest way to contribute is to use the library and star repository.
Questions 💭
Feel free to ask questions on GitHub Discussions.
Report bugs / request additional features 💡
Please register at GitHub Issues.
Development / Bug Fixes 🧑💻
See CONTRIBUTING.md.
Financial Support 💸
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 😊
ts-graphviz for Enterprise 🏢
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.
License ⚖️
This software is released under the MIT License, see LICENSE.
