Plugin SDK
Build plugins that extend Whatalo's admin with full-page iframe applications — from analytics dashboards to custom order management tools.
What is a Plugin?
A Whatalo plugin is a web application you host on your own server. It appears in the admin sidebar as one or more full-page views. Store owners install your plugin from the marketplace or directly via a private link.
You build it with any framework — the default template uses React and Vite. Communication between your plugin and the admin happens through the App Bridge, a postMessage protocol included in @whatalo/plugin-sdk.
How It Works
┌─────────────────────────────────────────────┐
│ Whatalo Admin │
│ │
│ Sidebar → /integrations/your-plugin │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ Plugin iframe │ │
│ │ (your server, sandboxed) │ │
│ │ │ │
│ │ ← whatalo:init (handshake) │ │
│ │ whatalo:action → (ready signal) │ │
│ │ ← whatalo:context (store data) │ │
│ │ whatalo:action → (toast, nav...) │ │
│ │ ← whatalo:ack (confirmation) │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
↕ REST API (scoped permissions)
Your plugin server ↔ Whatalo store data- You build a web app and host it on your own infrastructure
- Whatalo loads it in a sandboxed iframe inside the admin sidebar
- The App Bridge exchanges messages between your plugin and the admin
- Your server calls the Whatalo REST API using a scoped access token
Quick Install
npx create-whatalo-pluginFollow the prompts to name your plugin, then:
cd my-plugin
whatalo login
whatalo devOpen the admin dashboard — your plugin appears in the sidebar immediately.
What You Can Build
| Capability | How |
|---|---|
| Custom admin pages | adminUI.pages in manifest — each page is a sidebar entry |
| Store data access | REST API with 15 permission scopes (read:orders, write:products, etc.) |
| Real-time events | 13 webhook events (order.created, product.updated, etc.) |
| Admin actions | App Bridge: toast notifications, navigation, modals |
| Billing | Subscription plans with trials — monetize your plugin |
| Distribution | Private (own stores) or public via marketplace review |
SDK Sections
| Section | Description |
|---|---|
| Quick Start | Go from zero to a running plugin in under 15 minutes |
| Platform Overview | What the plugin platform is and how it fits together |
| Plugin Architecture | Iframe model, App Bridge protocol, security model |
| Prerequisites | What you need before you start |
| Build Your First Plugin | Full end-to-end tutorial |
| CLI Reference | All 14 CLI commands documented |
| Configuration | Manifest format, TOML config, permission scopes |
| App Bridge | Context hook, actions, billing bridge |
| API Client | REST API — products, orders, customers, inventory |
| Webhooks | 13 event types, verification, handling |
| Billing | Paid plans, trials, subscription management |
| UI Components | Pre-built components that match admin design language |
| Publishing | Submit for review and distribute |
| Best Practices | Security, performance, error handling |