figjam-plugin
npx machina-cli add skill aiskillstore/marketplace/figjam-plugin --openclawFigJam Plugin Development
Architecture
Two-thread model:
-
packages/plugin/src/code.ts- Main thread (Figma API, renderer)- NO browser APIs (window, document, fetch)
- Access to figma.* API
- Renders nodes/edges to FigJam canvas
-
packages/plugin/src/ui.ts- UI iframe (WebSocket client)- Browser APIs available
- Manages WebSocket connection to CLI
- Handles connection UI
Communication Flow
CLI (serve) ←→ WebSocket ←→ Plugin UI (ui.ts) ←→ postMessage ←→ Plugin Main (code.ts)
JSON Import (UI)
- Accepts DSL JSON (nodes as array) or IR JSON (nodes as object)
- Validates with
@figram/coreand normalizes to IR before posting to main thread - Validation errors are surfaced in the UI alert with path/message details
Build
cd packages/plugin && bun run build
Output: packages/plugin/dist/ (code.js, ui.html)
Import Plugin
- Open Figma Desktop
- Menu → Plugins → Development → Import plugin from manifest
- Select
packages/plugin/manifest.json
Debugging
- UI errors: Browser DevTools console (right-click plugin UI → Inspect)
- Main thread errors: Figma DevTools (Menu → Plugins → Development → Open console)
- WebSocket issues: Check UI console for connection status
Key Files
manifest.json- Plugin configurationsrc/code.ts- Canvas rendering logicsrc/ui.ts- WebSocket client and connection UIsrc/ui.html- UI template (bundled by build)src/icons/- AWS service icons
Source
git clone https://github.com/aiskillstore/marketplace/blob/main/skills/7nohe/figjam-plugin/SKILL.mdView on GitHub Overview
This skill covers the end-to-end FigJam plugin development workflow, including the main thread code.ts, the UI iframe ui.ts, and the WebSocket-based communication to the CLI. It also details the build and import steps to run, test, and debug a plugin inside FigJam. It emphasizes the two-thread architecture, message flow, and how JSON imports are validated before reaching the main thread.
How This Skill Works
The plugin runs as two threads: the main thread code.ts handles the Figma API and renders nodes/edges, while the UI iframe ui.ts runs in the browser context as a WebSocket client. The UI validates JSON as DSL or IR, normalizes to IR, and posts messages to the main thread via postMessage. Build outputs bundle artifacts (code.js and ui.html) in packages/plugin/dist, and the plugin is imported into Figma from manifest.json.
When to Use It
- Developing or updating the plugin’s main thread code (code.ts) or UI logic (ui.ts).
- Debugging or validating the WebSocket communication between the UI and the CLI.
- Preparing the plugin for build and distribution with bun run build.
- Importing the plugin into FigJam via manifest.json in Figma Desktop.
- Diagnosing errors using both UI DevTools and Figma DevTools for the main thread.
Quick Start
- Step 1: Build the plugin: cd packages/plugin && bun run build
- Step 2: Import the plugin into Figma: Menu → Plugins → Development → Import plugin from manifest and select packages/plugin/manifest.json
- Step 3: Open FigJam, run the plugin, and use the UI to connect via WebSocket; check UI console and Figma DevTools for issues
Best Practices
- Keep code.ts free of browser APIs; use FigJam/Figma APIs only.
- Treat the UI as a WebSocket client and separate concerns between UI and main thread.
- Validate JSON imports (DSL or IR) with @figram/core before posting to the main thread.
- Use the documented build step (bun run build) to produce dist/ artifacts.
- Debug with both UI console and Figma DevTools to isolate UI vs main thread issues.
Example Use Cases
- Rendering nodes and edges on the FigJam canvas from code.ts.
- Validating and normalizing DSL/IR JSON in the UI before posting to main thread.
- Diagnosing WebSocket connection issues via the UI console.
- Importing and running the plugin in FigJam from manifest.json in Figma Desktop.
- Inspecting and iterating on the plugin using the build output (code.js, ui.html).
