{"skill":{"slug":"miro-sdk","displayName":"Miro Web SDK Reference","summary":"Complete Miro Web SDK reference for building web plugins and desktop applications. Covers setup, core APIs (boards, shapes, text, items, selections, events),...","description":"---\nname: miro-sdk\ndescription: Complete Miro Web SDK reference for building web plugins and desktop applications. Covers setup, core APIs (boards, shapes, text, items, selections, events), authentication, real-time collaboration, examples in TypeScript/JavaScript, best practices, and error handling.\n---\n\n# Miro Web SDK\n\nThe Miro Web SDK enables you to build web plugins that extend Miro's functionality. Create custom tools, automate workflows, and integrate external data directly into Miro boards.\n\n## Quick Start\n\n**Install SDK:**\n```bash\nnpm install @mirohq/websdk-cli @mirohq/miro-webplugin\n```\n\n**Create Plugin:**\n```bash\nnpm create @mirohq/websdk-cli my-plugin\ncd my-plugin\nnpm start\n```\n\n**Hello World Plugin:**\n```typescript\nimport { Board } from '@mirohq/miro-webplugin';\n\nmiro.onReady(async () => {\n  console.log('Plugin ready!');\n  \n  // Get current board\n  const board = await miro.board.getInfo();\n  console.log('Board name:', board.name);\n  \n  // Listen for shape creation\n  miro.board.events.on('item:create', (event) => {\n    console.log('New item:', event.data);\n  });\n});\n```\n\n## Core Capabilities\n\n### 1. Board Interaction\n- Get board information (name, owner, size)\n- Listen to real-time events (item creation, updates, deletions)\n- Manage board selection and viewport\n- Access board history and undo/redo\n\n### 2. Create Items\n- Shapes (rectangles, circles, diamonds, etc.)\n- Text and rich text formatting\n- Images and embeds\n- Sticky notes and cards\n- Frames and groups\n\n### 3. Manipulate Items\n- Move, resize, rotate items\n- Change styling (colors, opacity, fonts)\n- Update content and properties\n- Apply connectors between shapes\n- Delete items\n\n### 4. Selection & Interaction\n- Get selected items\n- Listen to selection changes\n- Programmatically select items\n- Multi-select operations\n\n### 5. User Interaction\n- Viewport and zoom control\n- Notification system\n- Modal dialogs\n- Context menus\n- Keyboard shortcuts\n\n### 6. Collaboration Features\n- Real-time sync with other users\n- User presence indicators\n- Shared selections\n- Live editing\n\n### 7. Data Management\n- Metadata and custom properties\n- Board-level storage\n- Plugin configuration\n- Event tracking\n\n### 8. Advanced Features\n- Batch operations (bulk create/update)\n- Search and filtering\n- Viewport navigation\n- Animation support\n- Performance optimization\n\n## SDK Platforms\n\n### Web Plugin\nBrowser-based plugin running inside Miro app\n\n**Install:**\n```bash\nnpm install @mirohq/miro-webplugin\n```\n\n**Use:**\n```typescript\nimport { Board, Ui } from '@mirohq/miro-webplugin';\n\n// Access board\nconst board = await miro.board.getInfo();\n\n// Create UI\nmiro.ui.openPanel({\n  url: 'panel.html'\n});\n```\n\n### Desktop App\nStandalone desktop application using Electron\n\n**Install:**\n```bash\nnpm install @mirohq/miro-desktop\n```\n\n**Supported Platforms:**\n- macOS\n- Windows\n- Linux\n\n## Architecture\n\n### Plugin Structure\n```\nmy-plugin/\n├── src/\n│   ├── index.ts          # Main plugin code\n│   ├── panel.html        # UI panel\n│   ├── panel.ts          # Panel logic\n│   └── styles.css        # Styling\n├── manifest.json         # Plugin metadata\n├── package.json\n└── tsconfig.json\n```\n\n### Event Flow\n```\nUser Action\n  ↓\nBrowser/Electron\n  ↓\nMiro SDK\n  ↓\nEvent Handler\n  ↓\nAPI Call\n  ↓\nBoard Update\n  ↓\nReal-time Sync\n```\n\n## Authentication\n\n### Web Plugin Auth\nUses implicit flow - user already logged into Miro\n\n```typescript\nmiro.onReady(async () => {\n  // User automatically authenticated\n  const user = await miro.currentUser.get();\n  console.log('Current user:', user.name);\n});\n```\n\n### Scopes\nDefine what your plugin can do:\n\n```json\n{\n  \"requiredScopes\": [\n    \"board:read\",\n    \"board:write\",\n    \"identity:read\"\n  ]\n}\n```\n\n**Available Scopes:**\n- `board:read` - Read board data\n- `board:write` - Create/edit items\n- `board:history` - Access history\n- `identity:read` - Get current user info\n\n## Reference Files\n\nSee detailed documentation:\n- `references/setup-installation.md` - Project setup and installation\n- `references/core-apis.md` - Complete SDK API reference\n- `references/authentication.md` - Auth patterns and scopes\n- `references/examples.md` - TypeScript/JavaScript code examples\n- `references/best-practices.md` - Performance, security, reliability\n- `references/error-handling.md` - Error types and handling strategies\n\n## API Overview\n\n### Core Objects\n\n```typescript\n// Board\nmiro.board.getInfo()\nmiro.board.getAllItems()\nmiro.board.createShape(shape)\nmiro.board.getSelection()\nmiro.board.events\n\n// Items\nitem.move(deltaX, deltaY)\nitem.resize(width, height)\nitem.update(updates)\nitem.delete()\n\n// User\nmiro.currentUser.get()\n\n// UI\nmiro.ui.openPanel()\nmiro.ui.openModal()\nmiro.ui.notifyWithButton()\n\n// Viewport\nmiro.board.viewport.zoomIn()\nmiro.board.viewport.scrollTo()\n```\n\n## Events\n\n```typescript\n// Item events\nmiro.board.events.on('item:create', (event) => {})\nmiro.board.events.on('item:update', (event) => {})\nmiro.board.events.on('item:delete', (event) => {})\n\n// Selection events\nmiro.board.events.on('selection:change', (event) => {})\n\n// User events\nmiro.board.events.on('user:join', (event) => {})\nmiro.board.events.on('user:leave', (event) => {})\n```\n\n## Version History\n\n**Latest:** 2.0+\n**Support:** Web plugins, Desktop apps, Collaborative features\n\n## Getting Help\n\n- **Documentation:** https://developers.miro.com/docs\n- **API Reference:** https://developers.miro.com/reference\n- **GitHub:** https://github.com/miroapp/api-clients\n- **Community:** https://community.miro.com\n- **Support:** https://support.miro.com\n\n## Tutorials\n\n- Build your first plugin\n- Create interactive shapes\n- Real-time collaboration\n- Data integration\n- Performance optimization\n- Testing and debugging\n\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":514,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1772891191311,"updatedAt":1778491764944},"latestVersion":{"version":"1.0.0","createdAt":1772891191311,"changelog":"Initial release: Complete Web SDK documentation with setup/installation, core APIs (board, items, events, viewport), authentication patterns, TypeScript/JavaScript code examples, best practices (performance, security, UX), error handling strategies","license":null},"metadata":null,"owner":{"handle":"bigbubbaagent-bot","userId":"s17591ys68ptbj1gsdhv3zbkmx83mhj1","displayName":"bigbubbaagent-bot","image":"https://avatars.githubusercontent.com/u/262385618?v=4"},"moderation":null}