diagrams-js — Getting Started

Create cloud architecture diagrams as code using TypeScript. 2000+ node classes across 17+ providers (AWS, Azure, GCP, Kubernetes, etc.). Works in browsers, Node.js, Deno, and Bun.

Setup

NPM Installation

shell

npm install diagrams-js

Browser with CDN

html

<script type="importmap">
  {
    "imports": {
      "diagrams-js": "https://esm.sh/diagrams-js",
      "diagrams-js/": "https://esm.sh/diagrams-js/"
    }
  }
</script>

<script type="module">
  import { Diagram } from "diagrams-js";
  import { EC2 } from "diagrams-js/aws/compute";

  const diagram = Diagram("My Architecture");
  const server = diagram.add(EC2("Web Server"));
  const svg = await diagram.render();
  document.body.innerHTML = svg;
</script>

Basic Diagram

import { Diagram } from "diagrams-js";
import { EC2 } from "diagrams-js/aws/compute";
import { RDS } from "diagrams-js/aws/database";

const diagram = Diagram("Web Architecture", {
  direction: "TB", // Top to Bottom
});

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

web.to(db);

const svg = await diagram.render();
console.log(svg); // SVG string

Core Patterns

Installation with Package Managers

shell

# npm
npm install diagrams-js

# yarn
yarn add diagrams-js

# pnpm
pnpm add diagrams-js

# bun
bun add diagrams-js

First Diagram

import { Diagram } from "diagrams-js";

const diagram = Diagram("My First Diagram");
diagram.add(Node("Server"));

const svg = await diagram.render();

Using Cloud Provider Nodes

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" });

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"));

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

const svg = await diagram.render();

Rendering and Using Output

// In Node.js - save to file
import { writeFileSync } from "fs";

const svg = await diagram.render();
writeFileSync("diagram.svg", svg);

// In browser - display in DOM
const svg = await diagram.render();
document.getElementById("diagram").innerHTML = svg;

Common Mistakes

HIGH Not awaiting diagram.render()

Wrong:

const svg = diagram.render();
console.log(svg); // Promise, not string

Correct:

const svg = await diagram.render();
console.log(svg); // SVG string

Returns a Promise that resolves to SVG string, PNG/JPG Uint8Array, or DOT string depending on format option.

Source: source code - Diagram.ts render() returns Promise

HIGH Using wrong import path for providers

Wrong:

import { EC2 } from "diagrams-js/providers/aws/compute";

Correct:

import { EC2 } from "diagrams-js/aws/compute";

Provider paths use subpath imports without "/providers/" prefix.

Source: migration guide and package.json exports

CRITICAL Assuming nodes auto-register with diagram

Wrong:

const web = EC2("Web Server"); // Not added to diagram!
const db = diagram.add(RDS("Database"));
web.to(db); // Error: Node is not registered

Correct:

const web = diagram.add(EC2("Web Server"));
const db = diagram.add(RDS("Database"));
web.to(db); // Works

Unlike Python diagrams, TypeScript requires explicit diagram.add() for each node.

Source: migration guide from Python

diagrams-js