Local widget development

This guide covers tooling for widget authors working in a Vite project (Vue, React, or vanilla).

vite-plugin-doohnut-widget

The workspace package vite-plugin-doohnut-widget improves day-to-day widget development:

1. Dev overlay — Open the dev server at /. You get a mock host (INIT, FRAME_ENTER, CONFIG_UPDATE, TIME_TICK, STATE_*) and an iframe that loads your real app under /__widget-app__/ so Vite HMR works inside the iframe. Use the Viewport panel to change iframe width/height (and Apply) or use presets from doohnut.devOverlay.viewportPresets or the plugin option viewportPresets to test different section geometries.
2. Validation — On pnpm dev and vite build, checks that package.json has a valid doohnut block with width and height in a sane range, optional aspectRatioPolicy (mandatory | optional), and optional devOverlay.viewportPresets.
3. Optional pack — With DOOHNUT_PACK=1 or pack: true, after build writes a .tgz containing dist/ contents plus package.json at the archive root (suitable for upload as a widget asset).

Optional doohnut.devOverlay.presets in package.json adds named buttons in the overlay that merge preset config into the mock CONFIG_UPDATE JSON. Optional doohnut.devOverlay.viewportPresets adds named viewport size buttons. The overlay also shows a live STATE_* mock store. On Windows, prefer cross-env DOOHNUT_PACK=1 for pack scripts (see plugin README).

See the plugin README: packages/vite-plugin-doohnut-widget/README.md.

package.json manifest conventions

• aspectRatioPolicy: Use optional when the widget should tolerate playlist sections whose aspect differs from doohnut.width × doohnut.height (letterboxing / fill). Use mandatory or omit the field when you want the default strict match. During dev, use the overlay Viewport panel or doohnut.devOverlay.viewportPresets to try sizes that differ from your reference dimensions.

Examples

• dx-walkthrough-vue — minimal Vue + TypeScript + Tailwind sample for learning: SDK handshake, CONFIG_UPDATE, TIME_TICK, and frame visibility; aspectRatioPolicy: optional and responsive layout inside the design canvas. Start here for a short end-to-end path; the developer hub walkthrough narrates bootstrap, dev, debug, and deploy around this folder.
• footer-clock-weather-vue — 1920×200 reference footer with clock, Open-Meteo weather, aspectRatioPolicy: optional, ScaleToFitView, responsive stacking on narrow viewports, and DOOHNUT_PACK=1 packing.

Protocol reference

Wire-level message types and payloads: Widget runtime protocol.