Skip to main content

AI Guide

This guide is specifically designed for AI Large Language Models (LLMs) and autonomous agents to effectively use the diagrams-js library for generating cloud architecture diagrams.

llms.txt​

For optimal context when working with diagrams-js, use these specially formatted documentation files:

📄 llms.txt - Concise overview of the library, installation, basic usage, and key concepts

📄 llms-full.txt - Complete documentation including all guides, API reference, and examples

These files are specifically structured for AI consumption with:

  • Clear API signatures and type definitions
  • Code examples with expected outputs
  • Provider reference lists
  • Best practices and common patterns

See https://llmstxt.org/ for more information about llms.txt standards.

Skills​

diagrams-js provides skills for enhanced AI-assisted development.

Installation for AI Agents​

Using skills.sh:

# Add skills into your project
npx skills add hatemhosny/diagrams-js

Or using @tanstack/intent:

# Install skills into your project
npx @tanstack/intent@latest install

# Or use directly without installation
npx @tanstack/intent@latest show diagrams-js/getting-started

Available Skills​

SkillDescription
diagrams-js/getting-startedInstallation, first diagram, basic concepts
diagrams-js/diagram-configurationDirection, theme, curve style, attributes
diagrams-js/rendering-exportSVG, PNG, JPG, DOT, data URLs
diagrams-js/provider-nodes17+ providers, 2000+ node classes
diagrams-js/custom-nodesExternal icons, URLs, data URLs
diagrams-js/node-connectionsto(), from(), with(), Edge styling
diagrams-js/clusters-groupingClusters, nesting, organization
diagrams-js/browser-integrationCDN, DOM, data URLs, downloads
diagrams-js/nodejs-integrationFile system, sharp, local icons
diagrams-js/python-migrationPython to TypeScript conversion

Using Skills​

AI agents can load relevant skills automatically based on context:

  • Creating a new diagram → loads getting-started
  • Adding AWS/GCP/Azure nodes → loads provider-nodes
  • Connecting nodes with edges → loads node-connections
  • Rendering to different formats → loads rendering-export
  • Migrating from Python diagrams → loads python-migration

Key Concepts for AI Agents​

1. Diagram Structure​

import { Diagram } from "diagrams-js";

// Always create a diagram instance first
const diagram = Diagram("Architecture Name", {
  direction: "TB", // Top-Bottom (or "LR" for Left-Right)
});

2. Adding Nodes​

Nodes can be added using the add() method:

import { Diagram, Node } from "diagrams-js";

const diagram = Diagram("Example");

// Basic node (no icon)
const basicNode = diagram.add(Node("Label"));

// Provider nodes (auto-include icons)
import { EC2 } from "diagrams-js/aws/compute";
const server = diagram.add(EC2("Web Server"));

3. Creating Connections​

Use method chaining for connections:

import { Edge } from "diagrams-js";

// .to() - Forward direction (left to right)
nodeA.to(nodeB);

// Sequential connections
nodeA.to(nodeB).to(nodeC);

// Branching connections
nodeA.to([nodeB, nodeC]);

// Connect multiple nodes to one target
const nodes = [nodeB, nodeC, nodeD];
nodes.forEach((n) => n.to(nodeA));

// .from() - Reverse direction (right to left)
nodeB.from(nodeA);

// .with() - Undirected/bidirectional (no arrows)
nodeA.with(nodeB);

// With custom styling using Edge
nodeA.to(Edge({ color: "red", style: "dashed" }), nodeB);

4. Rendering Output​

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

// Use the SVG (save to file, display, etc.)

Common Patterns​

Web Application Architecture​

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

const diagram = Diagram("Web App Architecture");

const lb = diagram.add(ALB("Load Balancer"));
const web = diagram.add(EC2("Web Servers"));
const db = diagram.add(RDS("Database"));
const storage = diagram.add(S3("Assets"));

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

const svg = await diagram.render();

Microservices Pattern​

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

const diagram = Diagram("Microservices");

// Group related services using clusters
const apiCluster = diagram.cluster("API Gateway");
const auth = apiCluster.add(ECS("Auth Service"));
const rateLimiter = apiCluster.add(ECS("Rate Limiter"));

const servicesCluster = diagram.cluster("Services");
const userSvc = servicesCluster.add(ECS("User Service"));
const orderSvc = servicesCluster.add(ECS("Order Service"));
const paymentSvc = servicesCluster.add(ECS("Payment Service"));

// Connect clusters
auth.to([userSvc, orderSvc, paymentSvc]);

const svg = await diagram.render();

Provider Organization​

Cloud providers are organized hierarchically:

diagrams-js/
├── aws/
│   ├── compute/      # EC2, Lambda, etc.
│   ├── database/     # RDS, DynamoDB, etc.
│   ├── storage/      # S3, EBS, etc.
│   └── ...
├── azure/
│   ├── compute/
│   ├── database/
│   └── ...
└── gcp/
    ├── compute/
    ├── database/
    └── ...

Common Mistakes to Avoid​

Here are critical mistakes that AI agents should avoid:

Python Migration Issues​

When converting from Python diagrams:

  • ❌ Context managers: Python uses with Diagram():, TypeScript uses const diagram = Diagram()
  • ❌ Operators: Python uses >> / << / -, TypeScript uses .to() / .from() / .with()
  • ❌ Auto-registration: Python auto-registers nodes, TypeScript requires diagram.add()
  • ❌ Auto-render: Python auto-renders on exit, TypeScript requires await diagram.render()

Node Registration​

// ❌ Wrong: Node not registered
const web = EC2("Web Server");
web.to(db); // Error!

// ✅ Correct: Explicit registration
const web = diagram.add(EC2("Web Server"));
web.to(db); // Works!

Async Rendering​

// ❌ Wrong: Not awaiting
const svg = diagram.render();

// ✅ Correct: Always await
const svg = await diagram.render();

Import Paths​

// ❌ Wrong: Missing category
import { EC2 } from "diagrams-js/aws";

// ✅ Correct: Include category
import { EC2 } from "diagrams-js/aws/compute";

Connection Direction​

// For << arrow (db << api)
// ❌ Wrong
db.to(api);

// ✅ Correct
db.from(api);

Browser vs Node.js​

// ❌ Wrong in browser
import { writeFileSync } from "fs";
writeFileSync("out.svg", svg);

// ✅ Correct in browser
await diagram.save("diagram.svg");

Best Practices for AI Generation​

  1. Use descriptive node labels that explain the component's role
  2. Group related nodes using Cluster for better organization
  3. Set appropriate diagram direction based on the layout needs
  4. Import only needed providers to optimize bundle size
  5. Handle async operations properly with await diagram.render()
  6. Always register nodes with diagram.add() before connecting
  7. Load relevant skills for enhanced guidance on specific tasks

Environment Support​

  • Browsers: Direct usage with ES modules
  • Node.js/Deno/Bun: Save SVG to files using
    await diagram.save("filename.svg", { format: "svg" }); // or "png"/"jpeg"

Resources​