What a Widget Actually Is
A widget is a self-contained React app bundled into a single HTML file and served inside an iframe on the canvas. Each widget gets:- Its own iframe — sandboxed, cross-origin from the canvas
- A WebSocket connection — to a per-canvas storage backend (RecordRoom)
- Access to the SDK —
@spaces/sdkprovides hooks for storage, auth, theming, files, and more - API access — the
mcapiclient lets widgets call DeepSpace integrations (text generation, Google Calendar, web search, etc.)
The Stack
| Layer | Technology |
|---|---|
| UI | React + Tailwind CSS |
| Storage | Cloudflare Durable Objects (SQLite) via WebSocket |
| File storage | Cloudflare R2 |
| Build | esbuild (canvas widgets) / Vite (standalone sites) |
| Hosting | Cloudflare Workers + R2 |
| Auth | Clerk (standalone) / postMessage token relay (canvas) |
Key Concepts
Canvas Mode vs Standalone Mode
Widgets run in two contexts:- Canvas mode — embedded in an iframe on the DeepSpace canvas. Auth tokens come from the parent frame via
postMessage. - Standalone mode — deployed as an independent website (e.g.,
myapp.app.space). Full Clerk auth flow, its own URL, works outside DeepSpace.
main.tsx detects which context it’s in and wires up the correct providers automatically. You write your app in App.tsx and it works in both contexts.
The SDK (@spaces/sdk)
Everything your widget needs is available through the SDK:
| Import | What it gives you |
|---|---|
@spaces/sdk/storage | useQuery, useMutations, useUser, useTeams, useMessages, useYjsText, useR2Files |
@spaces/sdk/auth | isWidgetContext(), getWidgetAuthToken(), SpacesAuthProvider |
@spaces/sdk/theme | DeepSpaceThemeProvider, theme config types |
@spaces/sdk/config | getApiUrl() (auto-detects dev/staging/prod) |
@spaces/sdk | mcapi client for API calls |
Schemas
Every collection your widget uses is defined inschemas.ts. Schemas control:
- What fields each record has
- Who can read/write (role-based access)
- What happens when a record is created (auto-injecting
userId, timestamps, etc.)
This Section
Local Development
GitHub setup, local dev server, and push workflow
Storage
Where data lives and how the storage system works
Hooks Reference
Every hook in the SDK and how to use it
Integrations & APIs
Calling external services from your widget
Theming
How the theme system works and how to customize it