tldraw-creator

name	tldraw-creator
description	Programmatically create tldraw whiteboards and visualize them with a self-hosted tldraw instance. Create boards with shapes, text, and connectors, then deploy to a self-hosted server for collaborative editing and gallery management.
metadata	{"version":"0.1.0","author":"arisng","tags":["visualization","whiteboarding","diagramming","tldraw","self-hosted"]}
env	node

tldraw-creator Skill

Create and manage tldraw whiteboards programmatically, deploy self-hosted instances, and build collaborative whiteboarding workflows.

Overview

tldraw-creator enables agents to:

• Create whiteboards programmatically using the @tldraw/store API (shapes, text, connectors, frames)
• Deploy self-hosted instances via Docker or Node.js with PostgreSQL persistence
• Import/export boards as .tldraw JSON documents
• Manage board galleries and enable collaborative editing
• Visualize diagrams directly in whiteboards with custom shapes and layouts

Prerequisites

• Node.js 18+ (for programmatic board creation)
• Docker (optional, for self-hosted server deployment)
• PostgreSQL 12+ (optional, for persistent document storage)
• npm (for installing @tldraw packages)

Setup

Install tldraw Packages

Note: As of tldraw 3.x all tldraw functionality is bundled in the single tldraw package. The individual @tldraw/store, @tldraw/tlschema, @tldraw/ui, and @tldraw/editor sub-packages are still available but the tldraw meta-package is the recommended entry point.

# Recommended: single package (tldraw 3.x)
npm install tldraw react react-dom

# Optional: individual sub-packages for advanced use
npm install @tldraw/store @tldraw/tlschema
npm install pg yjs y-websocket  # For server + persistence
npm install express cors         # For API server (optional)

Vite / ESM Setup

tldraw ships dual CJS/ESM code. When using Vite, add lodash.isequalwith to optimizeDeps.include to avoid a missing-default-export error at runtime:

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    include: ['lodash.isequalwith', 'lodash.isequal'],
  },
})

Environment Variables

Create .env file in your skill workspace root or pass as process variables:

# Programmatic Board Creation
TLDRAW_EXPORT_FORMAT=json          # json | svg | png (default: json)

# Self-Hosted Server
TLDRAW_SERVER_PORT=3000
TLDRAW_DATABASE_URL=postgresql://user:password@localhost:5432/tldraw
TLDRAW_WEBSOCKET_URL=wss://tldraw.example.com
TLDRAW_NODE_ENV=development        # development | production

# Optional: Cloud Storage
TLDRAW_S3_BUCKET=my-tldraw-boards
TLDRAW_S3_REGION=us-east-1

Tool Calling Pattern

Tool: Create Board

Purpose: Programmatically generate a tldraw whiteboard with shapes, text, and connectors.

Input Schema:

{
  "name": "my-board",
  "title": "Project Architecture",
  "shapes": [
    {
      "id": "shape-1",
      "type": "geo",
      "x": 100,
      "y": 100,
      "props": {
        "w": 200,
        "h": 100,
        "geo": "rectangle",
        "color": "blue",
        "richText": { "type": "doc", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Frontend" }] }] }
      }
    }
  ],
  "theme": "dark"
}

tldraw 3.x: shape labels use richText (ProseMirror document), not text. Use toRichText(str) from the tldraw package to convert plain strings.

Output Schema:

{
  "success": true,
  "boardId": "doc_abc123",
  "boardName": "my-board",
  "exportPath": "/path/to/my-board.tldraw",
  "boardJson": { "/* TLStore snapshot */" }
}

Implementation: See scripts/create-board.js

Tool: Deploy Server

Purpose: Set up a self-hosted tldraw instance for visualization and collaboration.

Input Schema:

{
  "deploymentType": "docker",
  "persistenceType": "postgresql",
  "databaseUrl": "postgresql://tldraw:password@localhost:5432/tldraw",
  "serverPort": 3000,
  "enableWebSocket": true
}

Output Schema:

{
  "success": true,
  "serverUrl": "http://localhost:3000",
  "status": "running",
  "containerName": "tldraw-server",
  "logs": "Server started..."
}

Implementation: See scripts/deploy-server.js

Tool: Import Board to Server

Purpose: Upload a board JSON to a running self-hosted instance and get a visualization URL.

Input Schema:

{
  "serverUrl": "http://localhost:3000",
  "boardJson": { "/* TLStore snapshot */" },
  "boardName": "my-board"
}

Output Schema:

{
  "success": true,
  "boardId": "doc_abc123",
  "viewUrl": "http://localhost:3000/room/doc_abc123",
  "editUrl": "http://localhost:3000/edit/doc_abc123"
}

Implementation: See scripts/import-board.js

Tool: List Boards

Purpose: Get a list of all boards on a self-hosted instance (for gallery/management).

Input Schema:

{
  "serverUrl": "http://localhost:3000",
  "limit": 20,
  "sortBy": "created_at"
}

Output Schema:

{
  "success": true,
  "boards": [
    {
      "id": "doc_abc123",
      "name": "Project Architecture",
      "createdAt": "2026-04-26T12:00:00Z",
      "updatedAt": "2026-04-26T14:30:00Z",
      "url": "http://localhost:3000/room/doc_abc123"
    }
  ]
}

Implementation: See scripts/list-boards.js

Usage Examples

Example 1: Create and Deploy a Simple Diagram

User Request: "Create a diagram with 3 interconnected components and deploy it to a whiteboard"

Agent Flow:

1. Agent calls create-board with:
   - 3 geo shapes (rectangles)
   - 2 arrow connectors
   - Labels for each component

2. Agent calls deploy-server (if not already running)

3. Agent calls import-board-to-server with the generated board

4. Agent returns URL: http://localhost:3000/room/doc_abc123

Example 2: Create and Save a Flow Diagram

User Request: "Build a swimlane diagram for a user onboarding flow"

Agent Flow:

1. Agent designs shapes:
   - Frames for each swimlane (user, backend, email service)
   - Text boxes for steps
   - Arrows showing flow direction

2. Agent calls create-board

3. Board is saved as JSON to workspace: /my-swimlane-flow.tldraw

4. Agent can export to PNG/SVG if needed

Example 3: Build and Manage a Board Gallery

User Request: "Show me all my whiteboards and let me pick one to edit"

Agent Flow:

1. Agent calls list-boards on running server

2. Agent generates gallery UI with:
   - Board names and creation dates
   - Thumbnail previews
   - Links to view/edit each board

3. User selects a board → opens in tldraw viewer

Skill Scripts

scripts/create-board.js

Programmatically create a .tldraw file with shapes, bindings, and text.

Usage:

node scripts/create-board.js \
  --name "my-diagram" \
  --title "System Architecture" \
  --config config.json

Output: my-diagram.tldraw (JSON serialized TLStore snapshot)

See references/api-reference.md for detailed shape API.

scripts/deploy-server.js

Deploy a self-hosted tldraw instance using Docker or Node.js.

Usage:

node scripts/deploy-server.js \
  --type docker \
  --port 3000 \
  --database postgresql://localhost/tldraw

Output: Docker container running tldraw server, accessible at http://localhost:3000

See references/deployment-guide.md for detailed setup.

scripts/import-board.js

Import a board JSON into a running tldraw server.

Usage:

node scripts/import-board.js \
  --server http://localhost:3000 \
  --board my-diagram.tldraw \
  --name "My Diagram"

Output: Public URL to view/edit the board on the server.

scripts/list-boards.js

List all boards on a running server (for gallery management).

Usage:

node scripts/list-boards.js \
  --server http://localhost:3000 \
  --format json

Output: JSON array of board metadata.

Shape Types Reference

tldraw supports a rich set of shape types. See references/shape-reference.md for complete details.

Type	Example	Typical Use
geo	Rectangle, Ellipse, Diamond, Triangle	Flowchart nodes, diagrams
text	Text box	Labels, annotations, notes
arrow	Connector with arrowhead	Flow direction, relationships
frame	Container/artboard	Grouping shapes, swimlanes
image	Embedded image	Diagrams with images, photos
note	Sticky note shape	Quick notes, reminders
bookmark	Web link preview	References to external content

Deployment Guide

Quick Start: Self-Hosted with Docker

1. Install Docker: https://docs.docker.com/get-docker/

2. Run setup script:

   node scripts/deploy-server.js --type docker
   

3. Access: Open http://localhost:3000 in browser

4. Create boards and import:

   node scripts/create-board.js --name my-diagram
   node scripts/import-board.js --server http://localhost:3000 --board my-diagram.tldraw
   

Production Deployment

See references/deployment-guide.md for production considerations:

• Nginx reverse proxy with SSL/TLS
• WebSocket configuration
• PostgreSQL persistence
• Environment variable setup
• Health checks and monitoring

API Reference

Document Serialization Format

tldraw documents are JSON files with the .tldraw extension. Structure:

{
  "version": 15,
  "document": {
    "id": "doc_abc123",
    "pages": {
      "page_abc123": {
        "id": "page_abc123",
        "name": "Page 1",
        "shapes": { "/* shape objects */" },
        "bindings": { "/* binding objects */" }
      }
    },
    "assets": { "/* images, videos */" },
    "pageStates": { "/* UI state */" }
  }
}

Key Points:

• Documents can have multiple pages
• Shapes are keyed by ID in a dictionary
• Bindings define connections between shapes
• Assets store embedded media (base64 encoded)

See references/api-reference.md for complete schema and type definitions.

Known Breaking Changes (tldraw 3.x)

text → richText (tldraw 3.0+)

All shape props that previously accepted a plain string for label text now require a ProseMirror document object (richText). This affects both geo shapes and text shapes.

Shape type	Old prop (< 3.0)	New prop (≥ 3.0)