diagrams-js

A (vibe-coded) TypeScript/JavaScript port of the popular Python diagrams library for drawing cloud system architecture diagrams as code.

Features

• Diagram as Code: Define your architecture diagrams in TypeScript
• 17+ Cloud Providers: AWS, Azure, GCP, Kubernetes, Alibaba Cloud, Oracle Cloud, IBM Cloud, and more
• 2000+ Node Classes: Comprehensive coverage of cloud services and infrastructure components
• Cross-Platform: Works in browsers, Node.js, Deno and Bun
• Multiple Output Formats: SVG, PNG, JPG, and DOT
• Visual Diff: Compare diagram versions side-by-side with color-coded changes (added, removed, modified, renamed)
• Type-Safe: Full TypeScript support with comprehensive type definitions
• WebAssembly Powered: Uses a WebAssembly build of Graphviz (viz) for fast, client-side rendering
• Custom Nodes: Support for external icons and images
• Tree-Shakable: Import only what you need

Examples

Check the examples page for a full list of examples.

Interactive Playground

Check out the playground for a live demo of diagrams-js in your browser.

Installation

# npm
npm install diagrams-js

Quick Start

Node.js / TypeScript

import { Diagram } from "diagrams-js";
import { EC2, Lambda } from "diagrams-js/aws/compute";
import { RDS } from "diagrams-js/aws/database";
import { S3 } from "diagrams-js/aws/storage";
import { ALB } from "diagrams-js/aws/network";

const diagram = Diagram("AWS Architecture", { direction: "TB" });

// Create nodes with icons
const lb = diagram.add(ALB("Load Balancer"));
const web = diagram.add(EC2("Web Server"));
const api = diagram.add(Lambda("API"));
const db = diagram.add(RDS("Database"));
const storage = diagram.add(S3("Storage"));

// Connect them
lb.to(web).to(api);
api.to([db, storage]);

// Render to SVG
const svg = await diagram.render();

Visual Diff

Compare two versions of a diagram to see what changed:

import { Diagram } from "diagrams-js";
import { writeFileSync } from "fs";

// Load two versions (e.g., from git or saved JSON)
const before = JSON.parse(await fs.readFile("arch-v1.json", "utf8"));
const after = JSON.parse(await fs.readFile("arch-v2.json", "utf8"));

// Generate visual diff as self-contained HTML
const html = await Diagram.renderDiff(before, after, {
  format: "html",
  theme: "light",
  showUnchanged: "show", // "show" (default), "dim", or "hide"
});

await fs.writeFile("diff.html", html);

The diff shows:

• 🟢 Green: Added elements
• 🔴 Red: Removed elements
• 🟠 Amber: Modified elements (including label changes)

Browser

<script type="module">
  import { Diagram } from "https://esm.sh/diagrams-js";
  import { EC2 } from "https://esm.sh/diagrams-js/aws/compute";
  import { RDS } from "https://esm.sh/diagrams-js/aws/database";

  const diagram = Diagram("My Diagram");
  const web = diagram.add(EC2("Web Server"));
  const db = diagram.add(RDS("Database"));

  web.to(db);

  const svg = await diagram.render();
  document.body.innerHTML = svg;
</script>

Documentation

📚 Full documentation: https://diagrams-js.hatemhosny.dev

• Getting Started
• Examples
• Guides
• Providers
• Playground

Supported Providers

| Provider | Description | | -------------------------------------------------------------------------- | ---------------------------------------- | | AWS | Amazon Web Services nodes | | Azure | Microsoft Azure nodes | | GCP | Google Cloud Platform nodes | | Kubernetes | Kubernetes nodes | | OnPrem | On-premises infrastructure nodes | | AlibabaCloud | Alibaba Cloud nodes | | DigitalOcean | DigitalOcean nodes | | Elastic | Elastic Stack nodes | | Firebase | Firebase nodes | | Generic | Generic computing nodes | | GIS | GIS nodes | | IBM | IBM Cloud nodes | | OCI | Oracle Cloud Infrastructure nodes | | OpenStack | OpenStack nodes | | Outscale | Outscale nodes | | Programming | Programming language and framework nodes | | SaaS | SaaS application nodes |

View the full list

Development

Prerequisites

• Node.js 18+
• pnpm
• Vite+

Setup

# Clone the repository
git clone https://github.com/diagrams-js/diagrams-js.git
cd diagrams-js

# Install dependencies
vp install

# Run tests
vp test

# Run checks (lint, format, types)
vp check

# Build the library
vp run build

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Acknowledgments

This project is a TypeScript port of the excellent Python diagrams library by mingrammer.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Sponsor 💚

Please consider sponsoring the project, to support its ongoing development and maintenance, as well as help to ensure that it remains a valuable resource for the developer community.