This skill builds on diagrams-js/getting-started and diagrams-js/provider-nodes. Read them first for foundational concepts.

diagrams-js — Clusters & Grouping

Organize diagrams visually by grouping related nodes into clusters. Support for nested clusters with automatic themed backgrounds.

Setup

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

const diagram = Diagram("Clustered Services");

const webCluster = diagram.cluster("Web Tier");
const web = webCluster.add(ECS("Web Server"));

const dbCluster = diagram.cluster("Database Tier");
const db = dbCluster.add(RDS("Database"));

web.to(db);

const svg = await diagram.render();

Core Patterns

Basic Cluster

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

const diagram = Diagram("Services");

const cluster = diagram.cluster("Web Services");
const web1 = cluster.add(ECS("web1"));
const web2 = cluster.add(ECS("web2"));

Nested Clusters

const diagram = Diagram("Production");

const prod = diagram.cluster("Production");

const webTier = prod.cluster("Web Tier");
const web1 = webTier.add(ECS("web1"));
const web2 = webTier.add(ECS("web2"));

const dbTier = prod.cluster("Database Tier");
const primary = dbTier.add(RDS("Primary"));
const replica = dbTier.add(RDS("Replica"));

Cluster Options

Clusters accept an optional ClusterOptions object with className, dataAttrs, and graphAttr:

const cluster = diagram.cluster("VPC", {
  className: "production",
  dataAttrs: { region: "us-east-1" },
});

These are injected into the rendered SVG as attributes on the cluster <g> element, enabling DOM manipulation after rendering.

Nested clusters also support options:

const prod = diagram.cluster("Production", { className: "prod-env" });
const webTier = prod.cluster("Web Tier", { className: "web-tier" });

Connecting Across Clusters

const diagram = Diagram("Full Stack");

const frontend = diagram.cluster("Frontend");
const web = frontend.add(EC2("Web"));

const backend = diagram.cluster("Backend");
const api = backend.add(EC2("API"));

const data = diagram.cluster("Data");
const db = data.add(RDS("DB"));

web.to(api).to(db);

Cluster with Multiple Node Types

const diagram = Diagram("AWS Architecture");

const lb = diagram.add(ALB("Load Balancer"));

const webCluster = diagram.cluster("Web Tier");
const web1 = webCluster.add(ECS("web1"));
const web2 = webCluster.add(ECS("web2"));

const dbCluster = diagram.cluster("Database Tier");
const primary = dbCluster.add(RDS("Primary"));
const replica = dbCluster.add(RDS("Replica"));

lb.to([web1, web2]);
web1.to(primary);
web2.to(primary);
primary.with(replica);

Common Mistakes

HIGH Calling diagram.add() instead of cluster.add()

Wrong:

const vpc = diagram.cluster("VPC");
const server = diagram.add(EC2("Server"));
// Server added to diagram, NOT to the VPC cluster!

Correct:

const vpc = diagram.cluster("VPC");
const server = vpc.add(EC2("Server"));
// Server is inside the VPC cluster with themed background

Must use cluster.add() to place nodes inside cluster. diagram.add() adds to diagram root.

Source: docs/guides/clusters.mdx

CRITICAL Using Python Cluster context manager syntax

Wrong:

python

with Cluster("VPC"):
    server = EC2("Server")

Correct:

const vpc = diagram.cluster("VPC");
const server = vpc.add(EC2("Server"));

TypeScript uses method calls, not Python context managers. Create cluster with diagram.cluster(), add nodes with cluster.add().

Source: migration guide

diagrams-js