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.
The 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.
Install SDK:
npm install @mirohq/websdk-cli @mirohq/miro-webplugin
Create Plugin:
npm create @mirohq/websdk-cli my-plugin
cd my-plugin
npm start
Hello World Plugin:
import { Board } from '@mirohq/miro-webplugin';
miro.onReady(async () => {
console.log('Plugin ready!');
// Get current board
const board = await miro.board.getInfo();
console.log('Board name:', board.name);
// Listen for shape creation
miro.board.events.on('item:create', (event) => {
console.log('New item:', event.data);
});
});
Browser-based plugin running inside Miro app
Install:
npm install @mirohq/miro-webplugin
Use:
import { Board, Ui } from '@mirohq/miro-webplugin';
// Access board
const board = await miro.board.getInfo();
// Create UI
miro.ui.openPanel({
url: 'panel.html'
});
Standalone desktop application using Electron
Install:
npm install @mirohq/miro-desktop
Supported Platforms:
my-plugin/
├── src/
│ ├── index.ts # Main plugin code
│ ├── panel.html # UI panel
│ ├── panel.ts # Panel logic
│ └── styles.css # Styling
├── manifest.json # Plugin metadata
├── package.json
└── tsconfig.json
User Action
↓
Browser/Electron
↓
Miro SDK
↓
Event Handler
↓
API Call
↓
Board Update
↓
Real-time Sync
Uses implicit flow - user already logged into Miro
miro.onReady(async () => {
// User automatically authenticated
const user = await miro.currentUser.get();
console.log('Current user:', user.name);
});
Define what your plugin can do:
{
"requiredScopes": [
"board:read",
"board:write",
"identity:read"
]
}
Available Scopes:
board:read - Read board databoard:write - Create/edit itemsboard:history - Access historyidentity:read - Get current user infoSee detailed documentation:
references/setup-installation.md - Project setup and installationreferences/core-apis.md - Complete SDK API referencereferences/authentication.md - Auth patterns and scopesreferences/examples.md - TypeScript/JavaScript code examplesreferences/best-practices.md - Performance, security, reliabilityreferences/error-handling.md - Error types and handling strategies// Board
miro.board.getInfo()
miro.board.getAllItems()
miro.board.createShape(shape)
miro.board.getSelection()
miro.board.events
// Items
item.move(deltaX, deltaY)
item.resize(width, height)
item.update(updates)
item.delete()
// User
miro.currentUser.get()
// UI
miro.ui.openPanel()
miro.ui.openModal()
miro.ui.notifyWithButton()
// Viewport
miro.board.viewport.zoomIn()
miro.board.viewport.scrollTo()
// Item events
miro.board.events.on('item:create', (event) => {})
miro.board.events.on('item:update', (event) => {})
miro.board.events.on('item:delete', (event) => {})
// Selection events
miro.board.events.on('selection:change', (event) => {})
// User events
miro.board.events.on('user:join', (event) => {})
miro.board.events.on('user:leave', (event) => {})
Latest: 2.0+ Support: Web plugins, Desktop apps, Collaborative features