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
• 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();

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
• API Reference
• 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/hatemhosny/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

Project Structure

diagrams-js/
├── src/              # Source code
│   ├── index.ts      # Main exports
│   ├── Diagram.ts    # Core diagram class
│   ├── Node.ts       # Base node class
│   ├── Edge.ts       # Edge/connection class
│   ├── Cluster.ts    # Cluster/grouping class
│   └── providers/    # Auto-generated provider classes
├── resources/        # Icon resources (PNG files)
├── scripts/          # Build and generation scripts
├── tests/            # Test files
└── docs/             # Documentation site

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.