majiayu000 WebSocket Connection Debugging
Architecture
CLI serve (Bun) ←── WebSocket ──→ Plugin UI (ui.ts) ←── postMessage ──→ Plugin Main (code.ts)
│ │ │
File watcher Browser APIs Figma API
YAML parsing WebSocket client Canvas rendering
Common Issues
| Issue | Symptom | Solution |
|---|---|---|
| CLI not running | "Connecting..." indefinitely | Start bun run packages/cli/src/index.ts serve diagram.yaml |
| Port in use | Connection refused | Check lsof -i :3456, use different port |
| Secret mismatch | Connects then immediately closes | Match --secret value in CLI and plugin |
| YAML errors | Connected but no updates | Fix validation errors in CLI output |
| docId mismatch | No response after hello | Ensure plugin docId matches YAML docId |
| Patches not applied | Connected, canvas unchanged | Check Plugin Main console for render errors |
Debugging Steps
- CLI side: Check terminal for errors, verify YAML with
bun run packages/cli/src/index.ts build diagram.yaml - Plugin UI: Right-click plugin → Inspect → Console for WebSocket events
- Plugin Main: Figma Desktop → Plugins → Development → Open console
Message Flow
Plugin CLI
│ │
│──── hello ─────────────────►│ {type:"hello", docId, secret?}
│◄──── full ─────────────────│ {type:"full", rev, ir}
│ │
│ [YAML changes] │
│◄──── patch ────────────────│ {type:"patch", baseRev, nextRev, ops}
│ │
│ [Reconnect] │
│──── requestFull ───────────►│ {type:"requestFull", docId}
│◄──── full ─────────────────│
JSON Import Errors
- JSON must be an object with
version,docId,nodes - DSL format:
nodesas array - IR format:
nodesas object (Record) - Validation errors shown in alert with path + message
Quick Test
# Start server
bun run packages/cli/src/index.ts serve examples/diagram.yaml
# Test with wscat
wscat -c ws://localhost:3456
> {"type":"hello","docId":"test"}