Widget DX walkthrough

This guide follows the dx-walkthrough-vue example in the monorepo: Vue 3, TypeScript, Tailwind CSS, vite-plugin-doohnut-widget, and doohnut-widget-sdk. Use it to copy patterns for bootstrapping, day-to-day development, debugging, and packaging without reading only prose.

For a larger real-world SPA (weather API, more config), see Examples → footer-clock-weather-vue.

1. Bootstrap

Prerequisites: pnpm and a clone of the doohnut repo.

cd docs/widgets/examples/dx-walkthrough-vue
pnpm install   # from repo root: pnpm install (workspace)

The example is a workspace package: it resolves vite-plugin-doohnut-widget, doohnut-widget-sdk, and catalog versions of Vite, Vue, and Tailwind from the monorepo.

Open package.json and note the doohnut block: width / height (preview dimensions), optional config.fields for the marketplace / builder, and optional devOverlay.presets for one-click mock config in the dev overlay.

2. Develop

pnpm dev

• The root URL (/) is the Doohnut dev overlay: mock host + iframe loading your app at /__widget-app__/ so HMR works inside the iframe.
• vite-plugin-doohnut-widget must be registered early in vite.config.ts (see the example). The plugin validates the doohnut manifest when the dev server starts.

Read Local development for overlay behaviour (INIT, FRAME_ENTER / FRAME_EXIT, CONFIG_UPDATE, TIME_TICK, mock STATE_*).

3. Debug

• Browser DevTools on the iframe document (your widget): Console for logs; Application → Frames if you need to target /__widget-app__/ explicitly.
• Mock host buttons send protocol messages; toggle TIME_TICK every 1s to see the example’s clock and counter advance via the SDK’s timeTick event.
• CONFIG_UPDATE: edit the JSON textarea, then send — your widget should react through configUpdate (the walkthrough example also applies init defaults on load).
• Deep wire-level detail: Runtime protocol. For raw postMessage logging without the SDK, see the sdk-debugger row in Examples.

Common pitfalls: forgetting frameEnter / frameExit (visibility), or assuming init includes “already visible” — treat visibility as separate events (see Widget SDK). The dx-walkthrough-vue example skips timeTick work while the frame is hidden (frameExit) and refreshes the clock on frameEnter.

4. Deploy (high level)

1. Build — pnpm run build produces static assets under dist/ (same as a normal Vite app; the overlay is dev-only).
2. Pack — pnpm run pack runs the build with DOOHNUT_PACK=1 so the plugin writes a .tgz with dist/ contents and package.json at the archive root (suitable for upload as a widget asset). On Windows the example uses cross-env.
3. Upload / publish — follow your tenant or marketplace flow in the Doohnut app; canonical packaging and config tiers are described in widgets.md (repo).

See also

• Examples — index of sample widgets and GitHub links.
• Widget SDK — npm package and event API.
• Plugin README — vite-plugin-doohnut-widget (options, validation, pack).