tldraw-creator

# 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. ```bash # 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: ```js // 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: ```env # 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**: ```json { "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**: ```json { "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**: ```json { "deploymentType": "docker", "persistenceType": "postgresql", "databaseUrl": "postgresql://tldraw:password@localhost:5432/tldraw", "serverPort": 3000, "enableWebSocket": true } ``` **Output Schema**: ```json { "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**: ```json { "serverUrl": "http://localhost:3000", "boardJson": { "/* TLStore snapshot */" }, "boardName": "my-board" } ``` **Output Schema**: ```json { "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**: ```json { "serverUrl": "http://localhost:3000", "limit": 20, "sortBy": "created_at" } ``` **Output Schema**: ```json { "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**: ```bash 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**: ```bash 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**: ```bash 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**: ```bash 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**: ```bash node scripts/deploy-server.js --type docker ``` 3. **Access**: Open `http://localhost:3000` in browser 4. **Create boards and import**: ```bash 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: ```json { "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) | |-----------|-----------------|------------------|