How koosoli/esphomedesigner works
ESPHome Designer is a browser-based, plugin-driven visual editor for smart-display layouts, usable standalone or through Home Assistant. Users arrange widgets on pages, configure properties and device settings, then export platform-specific output or save layouts; existing ESPHome, OEPL, and OpenDisplay configurations can be imported for round-trip editing. The frontend also supports AI-assisted layout generation and entity/MQTT data sources. The map combines README-documented capabilities with sampled frontend wiring and backend storage evidence; unsampled subsystem links are shown only where documented.
Main entry points: main.js Editor runtime · layout_manager_workflows.js Multi-page layouts · features Widget plugins · snippet_manager.js YAML snippet editor
Components 24
Visual editor
- Editor runtime
custom_components/esphome_designer/frontend/js/main.js - Canvas editor
custom_components/esphome_designer/frontend/js/core/canvas.js - Widget palette
custom_components/esphome_designer/frontend/js/ui/widget_palette.js - Widget properties
custom_components/esphome_designer/frontend/js/core/properties.js - Editor settings
custom_components/esphome_designer/frontend/js/ui/editor_settings.js - Multi-page layouts
custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js
Widget system
- Widget plugins
custom_components/esphome_designer/frontend/features - Plugin registry
custom_components/esphome_designer/frontend/js/core/plugin_registry.js
Import and export
- YAML snippet editor
custom_components/esphome_designer/frontend/js/ui/snippet_manager.js - YAML import
custom_components/esphome_designer/frontend/js/io/yaml_import.ts - Display parser
custom_components/esphome_designer/frontend/js/io/yaml_parsers/display_parser.js - Platform exporters
custom_components/esphome_designer/frontend/js/io/adapters - AI assistant
custom_components/esphome_designer/frontend/js/io/ai_service.js
Home Assistant integration
- Home Assistant API
custom_components/esphome_designer/frontend/js/io/ha_api.js - Integration API
custom_components/esphome_designer/http_api.py - HA services
custom_components/esphome_designer/services.py - Layout storage
custom_components/esphome_designer/storage.py
Project state
- Editor state
custom_components/esphome_designer/frontend/js/core/stores/index.ts - Widget manager
custom_components/esphome_designer/frontend/js/core/stores/app_state/widget_manager.js - Event bus
custom_components/esphome_designer/frontend/js/core/events.js - Layout models
custom_components/esphome_designer/models.py
Other components
- Designer user
- Home Assistant
- MQTT broker
Connections 27
- Designer user → Editor runtime: uses
- Editor runtime → Canvas editor: initializes
custom_components/esphome_designer/frontend/js/main.js - Editor runtime → Widget palette: renders
custom_components/esphome_designer/frontend/js/main.js - Editor runtime → Widget properties: initializes
custom_components/esphome_designer/frontend/js/main.js - Editor runtime → Editor settings: initializes
custom_components/esphome_designer/frontend/js/main.js - Widget palette → Plugin registry: discovers
- Plugin registry → Widget plugins: registers
- Canvas editor → Widget manager: edits
- Widget manager → Event bus: emits changes
custom_components/esphome_designer/frontend/js/core/stores/app_state/widget_manager.js - Editor state → Widget manager: constructs
custom_components/esphome_designer/frontend/js/core/stores/index.ts - Designer user → Multi-page layouts: manages pages
- Multi-page layouts → Home Assistant API: requests layouts
custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js - Multi-page layouts → YAML import: loads layout
custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js - Designer user → YAML snippet editor: edits YAML
- YAML snippet editor → Platform exporters: generates snippet
custom_components/esphome_designer/frontend/js/ui/snippet_manager.js - YAML snippet editor → YAML import: imports YAML
- YAML import → Display parser: parses display
custom_components/esphome_designer/frontend/js/io/yaml_parsers/display_parser.js - Designer user → Platform exporters: exports design
- Designer user → AI assistant: prompts layouts
- Designer user → Home Assistant API: saves layouts
- Home Assistant API → Integration API: calls integration
- Integration API → Layout storage: persists state
- HA services → Layout storage: reads and writes
custom_components/esphome_designer/services.py - Layout storage → Layout models: persists models
custom_components/esphome_designer/storage.py - Widget plugins → Home Assistant: reads entity data
- Widget plugins → MQTT broker: reads topics
- Designer user → Home Assistant: integrates device