excalidraw2png

CLI tool to validate and convert .excalidraw files to PNG. Designed for AI agent workflows — generate .excalidraw JSON, validate it, convert to PNG.

Quick Start

# No installation needed (recommended)
npx excalidraw2png validate diagram.excalidraw
npx excalidraw2png convert diagram.excalidraw -o output.png

Or install globally:

npm install -g excalidraw2png
excalidraw2png validate diagram.excalidraw
excalidraw2png convert diagram.excalidraw -o output.png

Commands

validate

Check .excalidraw file format. Returns structured errors with fix suggestions.

npx excalidraw2png validate diagram.excalidraw

# JSON output (for programmatic use)
npx excalidraw2png validate diagram.excalidraw --json

Exit code: 0 = valid, 1 = has errors.

Three validation layers:

| Layer | Scope | Severity | |-------|-------|----------| | L1 | File structure (type, elements, appState, files) | Fatal — blocks convert | | L2 | Element fields (required fields, type enums, numeric ranges) | Error — element may render wrong | | L3 | Reference integrity (boundElements, containerId, arrow bindings) | Warning — non-blocking |

Error format (designed for AI agents):

ERROR [L2] $.elements[3].strokeStyle (rectangle): got "wavy", expected ["solid","dashed","dotted"]. Fix: change strokeStyle to one of: solid, dashed, dotted

JSON output (--json) returns:

{
  "valid": false,
  "errors": [
    {
      "level": "L2",
      "path": "$.elements[3].strokeStyle",
      "elementId": "abc123",
      "elementType": "rectangle",
      "field": "strokeStyle",
      "got": "wavy",
      "expected": ["solid", "dashed", "dotted"],
      "fix": "change strokeStyle to one of: solid, dashed, dotted"
    }
  ],
  "warnings": [],
  "summary": {
    "totalElements": 5,
    "validElements": 4,
    "errorCount": 1,
    "warningCount": 0
  }
}

convert

Render .excalidraw file to PNG.

npx excalidraw2png convert diagram.excalidraw -o output.png

# Options
npx excalidraw2png convert diagram.excalidraw -o output.png --scale 2
npx excalidraw2png convert diagram.excalidraw -o output.png --no-background
npx excalidraw2png convert diagram.excalidraw -o output.png --padding 20

| Option | Default | Description | |--------|---------|-------------| | -o, --output <path> | (required) | Output PNG file path | | --scale <n> | 1 | Export scale factor (2 = retina) | | --no-background | false | Transparent background | | --padding <n> | 10 | Padding around content in pixels |

Convert runs validation first. L1 errors block conversion, L2 errors print warnings but proceed.

Supported Elements

| Element | Status | |---------|--------| | rectangle | Supported (with roundness) | | ellipse | Supported | | diamond | Supported | | text | Supported (3 font families, multi-line, alignment) | | arrow | Supported (arrowheads, bindings) | | line | Supported | | freedraw | Not yet | | image | Not yet | | frame | Not yet |

Rendering Details

• Uses RoughJS for hand-drawn style rendering (same as Excalidraw)
• Same seed value produces identical strokes
• Fill styles: solid, hachure, cross-hatch, zigzag
• Stroke styles: solid, dashed, dotted
• Font families: Virgil (hand-drawn), Helvetica (sans-serif), Cascadia (monospace)

For AI Agents

Typical workflow:

1. Generate .excalidraw JSON
2. npx excalidraw2png validate file.excalidraw --json
3. If errors → read "fix" field → correct JSON → re-validate
4. npx excalidraw2png convert file.excalidraw -o output.png

Minimal valid .excalidraw file:

{
  "type": "excalidraw",
  "version": 2,
  "source": "agent",
  "elements": [
    {
      "type": "rectangle",
      "id": "r1",
      "x": 0, "y": 0, "width": 200, "height": 100,
      "angle": 0,
      "strokeColor": "#1e1e1e",
      "backgroundColor": "transparent",
      "fillStyle": "solid",
      "strokeWidth": 2,
      "strokeStyle": "solid",
      "roughness": 1,
      "opacity": 100,
      "seed": 1,
      "version": 1,
      "versionNonce": 1,
      "isDeleted": false,
      "groupIds": [],
      "boundElements": null,
      "link": null,
      "locked": false,
      "roundness": null
    }
  ],
  "appState": { "viewBackgroundColor": "#ffffff" },
  "files": {}
}

Requirements

• Node.js >= 18
• The canvas npm package requires system-level Cairo. On most systems this is handled automatically. If you get build errors, see node-canvas prerequisites.

License

MIT