Excalidrawer

A diagram generation tool with built-in templates and a CLI. For supported diagram types, just provide JSON data and run the CLI. For custom diagrams, write a short JS script using the library API.

Prerequisites

No install needed for template-based workflows — npx handles everything automatically.

Only install the npm package if you need the library API for custom scripts:

npm install excalidrawer

Workflow: Template-Based (Preferred)

For supported diagram types (timeline, etc.), use the CLI directly — no script needed.

Step 1: Identify the diagram type

Check if the request matches a built-in template:

Run npx excalidrawer types to see all available types.

Step 2: Create a JSON data file

Write a JSON file matching the template's schema (see Template Schemas below).

Step 3: Run the CLI

npx excalidrawer generate --type <type> --input data.json --output ./path/to/output

CLI options:

• --type, -t — Diagram type (required)
• --input, -i — Input JSON file (reads stdin if omitted)
• --output, -o — Output path without extension (required)
• --format, -f — Comma-separated: excalidraw,svg,png (default: all three)
• --seed, -s — Seed for deterministic IDs

Examples:

# Generate all formats
npx excalidrawer generate -t timeline -i timeline.json -o docs/timeline

# Only SVG and PNG
npx excalidrawer generate -t timeline -i timeline.json -o docs/timeline -f svg,png

# Pipe from stdin
echo '{"title":"My Timeline","items":[...]}' | npx excalidrawer generate -t timeline -o out/timeline

Template Schemas

Architecture

Input JSON:

{
  "title": "My System",
  "sections": [
    {
      "label": "Users",
      "color": "yellow",
      "items": [
        { "label": "Web User", "color": "yellow", "desc": "Browser-based access" },
        { "label": "API User", "color": "orange", "desc": "Programmatic access" }
      ]
    },
    {
      "label": "Services",
      "color": "blue",
      "items": [
        { "label": "Auth Service", "color": "blue" },
        { "label": "Data API",     "color": "green" }
      ]
    },
    {
      "label": "Storage",
      "color": "gray",
      "items": ["PostgreSQL", "Redis"]
    }
  ],
  "connections": [
    { "from": "Web User",     "to": "Auth Service" },
    { "from": "Auth Service", "to": "PostgreSQL",  "style": "dashed" }
  ]
}

Fields:

• title (string, optional) — Diagram title at the top
• sections (array) — Horizontal layers stacked top to bottom
  • label (string) — Section heading (e.g. "Users", "Interface", "Backend")
  • color (string, optional) — Section palette: blue green yellow purple red orange gray
  • items (array) — Boxes inside the section, laid out horizontally
    • Short form: "Label string"
    • Full form: { label, color?, desc? }
    • label — Box title. Long labels auto-wrap within the box; box height grows to fit. Box width auto-sizes to the longest label across all sections, so one very long label widens every box.
    • desc (string, optional) — Small grey caption rendered below the box; use this for sub-details instead of cramming everything into the label
• connections (array, optional) — Arrows between items across sections
  • from / to — Must exactly match the item's label string
  • label (string, optional) — Text shown on the arrow
  • style — "solid" (default) or "dashed"

Sequence

Input JSON:

{
  "title": "OAuth Login Flow",
  "actors": [
    { "label": "User / CLI",      "color": "yellow" },
    { "label": "Local Client",    "color": "blue"   },
    { "label": "OAuth Server",    "color": "purple" }
  ],
  "steps": [
    {
      "actor": "User / CLI",
      "text":  "1. Run login command"
    },
    {
      "actor": "Local Client",
      "text":  "2. Start callback server\nlocalhost:PORT",
      "from":  "User / CLI",
      "arrow": ""
    },
    {
      "actor": "OAuth Server",
      "text":  "3. Show login page",
      "from":  "Local Client",
      "arrow": "GET /authorize"
    },
    {
      "actor": "User / CLI",
      "text":  "4. User authorizes",
      "from":  "OAuth Server",
      "arrow": "(page rendered)",
      "style": "dashed"
    },
    {
      "actor": "Local Client",
      "text":  "5. Receive token",
      "color": "green",
      "from":  "OAuth Server",
      "arrow": "200 OK token"
    }
  ]
}

Fields:

• title (string, optional) — Diagram title at the top, centered
• actors (array) — The participant columns, left to right
  • label (string) — Actor name, shown as column header; also used as reference key in steps
  • color (string, optional) — Header box color: yellow blue purple orange green red gray. Defaults to cycling through the palette.
• steps (array) — Events in chronological order, each occupying one row
  • actor (string) — Which actor column this step box belongs to (must match an actor label)
  • text (string) — Box content. Long text auto-wraps within the box; box height grows to fit. You can also use \n for explicit line breaks.
  • color (string, optional) — Override box color (e.g. "green" for a success/final step)
  • from (string, optional) — Source actor label. When set, draws a horizontal arrow from that actor's lifeline into this step box. The arrow Y is aligned to this box's center, ensuring perfect horizontal alignment.
  • arrow (string, optional) — Label shown above the arrow line. Use "" for an unlabelled arrow.
  • style (string, optional) — Arrow style: "solid" (default) or "dashed" (for return/async flows)

Flowchart

Input JSON:

{
  "title": "Deployment Pipeline",
  "direction": "horizontal",
  "nodes": [
    { "id": "start", "label": "Push Code", "type": "start" },
    { "id": "build", "label": "Build & Test", "type": "process" },
    { "id": "check", "label": "Tests Pass?", "type": "decision" },
    { "id": "deploy", "label": "Deploy to Prod", "type": "process" },
    { "id": "done", "label": "Done", "type": "end" },
    { "id": "fix", "label": "Fix Errors", "type": "end" }
  ],
  "edges": [
    { "from": "start", "to": "build" },
    { "from": "build", "to": "check" },
    { "from": "check", "to": "deploy", "label": "Yes" },
    { "from": "check", "to": "fix", "label": "No" },
    { "from": "deploy", "to": "done" }
  ]
}

Fields:

• title (string, optional) — Diagram title
• direction (string, optional) — "horizontal" (default) or "vertical"
• nodes (array) — Diagram nodes
  • id (string) — Unique identifier, referenced by edges
  • label (string) — Display text. Long labels auto-wrap; node height grows to fit.
  • type (string, optional) — "process" (default, rectangle), "decision" (diamond), "start" / "end" (rounded), "io" (rectangle)
  • color (string, optional) — Override fill color
• edges (array) — Connections between nodes
  • from / to — Node id values
  • label (string, optional) — Text on the edge (e.g. "Yes" / "No")

Timeline

Input JSON:

{
  "title": "Project Timeline",
  "items": [
    {
      "label": "Milestone 1",
      "time": "Jan",
      "desc": "Description line 1\nline 2"
    },
    {
      "label": "Milestone 2",
      "time": "Mar",
      "desc": "Another description",
      "color": "#a5d8ff"
    }
  ]
}

Fields:

• title (string) — Diagram title displayed at top
• items (array) — Milestones in chronological order
  • label (string) — Milestone name (displayed in colored box)
  • time (string) — Time label (displayed near the axis)
  • desc (string) — Description text. Use \n for line breaks.
  • color (string, optional) — Box fill color. If omitted, cycles through: yellow → blue → green → purple → red → orange

Workflow: Custom Script (Fallback)

For diagram types not covered by templates, write a JS script using the library API.

Core API

import {
  setSeed,            // setSeed(n) — set seed for deterministic IDs
  box,                // box(rid, tid, x, y, w, h, bg, text, fontSize?) → [rect, text]
  diamondBox,         // diamondBox(rid, tid, x, y, w, h, bg, text, fontSize?) → [diamond, text]
  arrow,              // arrow(id, x, y, points, extra?) → arrow element
  textEl,             // textEl(id, x, y, w, h, text, fontSize, extra?) → text element
  rect,               // rect(id, x, y, w, h, bg, extra?) → rectangle
  diamond,            // diamond(id, x, y, w, h, bg, extra?) → diamond shape
  ellipse,            // ellipse(id, x, y, w, h, bg, extra?) → ellipse shape
  colors,             // semantic color palette
  excalidraw,         // excalidraw(elements) → JSON string for .excalidraw file
  toSvg,              // toSvg(elements) → SVG string
  toPng,              // toPng(elements, scale?) → Promise<Buffer>
  wrapText,           // wrapText(text, maxWidth, fontSize) → wrapped string with \n
  estimateTextWidth,  // estimateTextWidth(text, fontSize) → pixel width estimate
  timeline,           // timeline(data, opts?) → elements array
  flowchart,          // flowchart(data, opts?) → elements array
  architecture,       // architecture(data, opts?) → elements array
  sequence,           // sequence(data, opts?) → elements array
} from 'excalidrawer';

Color Palette

colors.blue      // "#a5d8ff"  — info / process steps
colors.green     // "#b2f2bb"  — success / output
colors.yellow    // "#ffd43b"  — start / highlight
colors.purple    // "#d0bfff"  — AI / service layer
colors.red       // "#ffc9c9"  — external / warning
colors.orange    // "#ffec99"  — decision / human-in-loop
colors.gray      // "#e9ecef"  — secondary / misc

// Lighter section backgrounds
colors.bgBlue / colors.bgGreen / colors.bgYellow / colors.bgPurple

// Stroke accents
colors.strokeBlue / colors.strokeGreen / colors.strokeYellow / colors.strokeOrange

Script Example

import { writeFileSync } from "fs";
import { setSeed, box, arrow, textEl, colors, excalidraw, toSvg, toPng } from "excalidrawer";

setSeed(100000);
const CY = 150, BH = 56, BY = CY - BH / 2;

const elements = [
  textEl("title", 20, 12, 500, 28, "My Diagram", 22),
  ...box("s1", "s1t", 20, BY, 130, BH, colors.yellow, "Start", 15),
  arrow("a1", 150, CY, [[0,0],[40,0]]),
  ...box("s2", "s2t", 190, BY, 150, BH, colors.blue, "Process", 14),
];

writeFileSync("diagram.excalidraw", excalidraw(elements));
writeFileSync("diagram.svg", toSvg(elements));
writeFileSync("diagram.png", await toPng(elements, 2));

Run: node diagram.mjs

Visual Design Guidelines

Follow these principles so diagrams feel readable and well-spaced:

Labels

• Long labels auto-wrap — all templates automatically wrap text that exceeds the box width. Box heights grow to fit. No need to manually insert \n for line breaks.
• Prefer concise labels — shorter labels produce cleaner diagrams. The architecture template auto-widens every box to fit the longest label, so one very long label widens all boxes.
• Use desc for secondary info — put sub-details (URLs, tech stack, short notes) in the desc field, not in the label. desc renders as a small grey caption below the box and doesn't affect box sizing.

Titles

• Keep titles under ~60 characters — the canvas width is driven by item count × box width. A very long title can exceed the auto-computed canvas width and appear clipped. Shorten or split into title + subtitle.

Color usage

• Use color to encode meaning, not decoration:
  • yellow / orange → users, humans, external actors
  • blue → primary services, interface layer
  • purple → AI, ML, protocol layer
  • green → core logic, success state, data layer
  • gray → infrastructure, storage, secondary systems
  • red → warnings, external dependencies, risky paths
• Assign one color per architectural layer / role for visual consistency

Connections

• Prefer direct vertical connections (same column) — they render as straight arrows
• Diagonal connections (different columns) render as L-shaped paths; avoid too many to prevent visual clutter

Z-order (rendering layers)

When writing custom scripts, always control element order to avoid arrows obscuring text:

1. Background rects first (bottom layer)
2. Arrows / connections second (middle layer)
3. Boxes, labels, desc text last (top layer)

The architecture template handles this automatically. In custom scripts, use separate arrays and spread them in the right order:

const bg = [], conn = [], fg = [];
// ... push elements into the right bucket ...
const elements = [...bg, ...conn, ...fg];

Common Mistakes to Avoid

• Do NOT forget to spread ...box(...) — it returns an array of two elements
• Do NOT reuse element IDs — use setSeed() with different values per diagram
• Arrows: x, y is the start point; points are relative offsets

Export Format Decision

• Default to all three: .excalidraw + .svg + .png
• "for Markdown / GitHub" → .svg
• "for Lark / Notion / slides" → .png
• "I want to edit it" → .excalidraw

References

• Package source: https://github.com/guohaonan-shy/excalidrawer
• Excalidraw element spec: https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts