Tutorial de DX para widgets

Este guia acompanha o exemplo dx-walkthrough-vue no monorepo: Vue 3, TypeScript, Tailwind CSS, vite-plugin-doohnut-widget e doohnut-widget-sdk. Use-o para copiar padrões de bootstrap, desenvolvimento, depuração e empacotamento sem depender só de texto.

Para um SPA maior (API de clima, mais configuração), veja Exemplos → footer-clock-weather-vue.

1. Bootstrap

Pré-requisitos: pnpm e um clone do repositório doohnut.

cd docs/widgets/examples/dx-walkthrough-vue
pnpm install   # na raiz do monorepo: pnpm install (workspace)

O exemplo é um pacote do workspace: resolve vite-plugin-doohnut-widget, doohnut-widget-sdk e as versões de Vite, Vue e Tailwind do catálogo.

Abra o package.json e veja o bloco doohnut: width / height (dimensões de preview), config.fields opcional (marketplace / builder) e devOverlay.presets opcional para configuração simulada na sobreposição de desenvolvimento.

2. Desenvolver

pnpm dev

• A URL raiz (/) é a sobreposição de desenvolvimento Doohnut: host simulado + iframe carregando o app em /__widget-app__/, com HMR dentro do iframe.
• Registre vite-plugin-doohnut-widget no início da lista de plugins em vite.config.ts (veja o exemplo). O plugin valida o manifesto doohnut ao subir o servidor de desenvolvimento.

Leia Desenvolvimento local para o comportamento do overlay (INIT, FRAME_ENTER / FRAME_EXIT, CONFIG_UPDATE, TIME_TICK, STATE_* simulado).

3. Depurar

• DevTools no documento do iframe (seu widget): Console; Application → Frames se precisar mirar em /__widget-app__/.
• Botões do host simulado enviam mensagens do protocolo; ative TIME_TICK every 1s para ver o relógio e o contador do exemplo avançarem pelo evento timeTick do SDK.
• CONFIG_UPDATE: edite o JSON e envie — o widget deve reagir via configUpdate (o exemplo também aplica defaults do init no carregamento).
• Detalhe do protocolo: Protocolo de runtime. Para log de postMessage sem o SDK, use o sdk-debugger em Exemplos.

Armadilhas comuns: esquecer frameEnter / frameExit (visibilidade), ou assumir que init já indica “visível” — trate visibilidade como eventos separados (veja SDK do widget). O exemplo dx-walkthrough-vue ignora trabalho em timeTick enquanto o frame está oculto (frameExit) e atualiza o relógio em frameEnter.

4. Implantação (visão geral)

1. Build — pnpm run build gera assets estáticos em dist/ (como um app Vite normal; o overlay é só em desenvolvimento).
2. Pack — pnpm run pack roda o build com DOOHNUT_PACK=1 para o plugin gerar um .tgz com o conteúdo de dist/ e package.json na raiz do arquivo (adequado para upload como asset de widget). No Windows o exemplo usa cross-env.
3. Upload / publicação — siga o fluxo do tenant ou marketplace no app Doohnut; empacotamento e níveis de configuração estão em widgets.md (repositório, em inglês).

Ver também

• Exemplos — índice de widgets de exemplo e links no GitHub.
• SDK do widget — pacote npm e API de eventos.
• README do plugin — vite-plugin-doohnut-widget (opções, validação, pack).