A (vibe-coded) TypeScript/JavaScript port of the popular Python diagrams library for drawing cloud system architecture diagrams as code.
- 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
Check the examples page for a full list of examples.
Check out the playground for a live demo of diagrams-js in your browser.
# npm
npm install diagrams-jsimport { 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();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)
<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>📚 Full documentation: https://diagrams-js.hatemhosny.dev
| 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
- Node.js 18+
- pnpm
- Vite+
# 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 buildWe welcome contributions! Please see our Contributing Guide for details.
This project is a TypeScript port of the excellent Python diagrams library by mingrammer.
This project is licensed under the MIT License - see the LICENSE file for details.
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.