Getting Started#

A widget is a SolidJS component + a Zod config schema, wrapped with defineWidget. The dashboard renders the component, auto-generates the settings form from the schema, and feeds in entity state.

The bun widget <cmd> form works inside scaffolded projects (they pin the CLI in devDependencies and ship a widget script alias to glasshome-widget). Outside a project, use bunx @glasshome/widget-cli@latest <cmd>. See Widget CLI for the full command list and details.

Prerequisites#

Scaffolded projects ship a .mise.toml pinning the versions. Install mise and run mise install.

Quickstart#

1. 1

   Scaffold a project

   bunx @glasshome/widget-cli@latest
   cd <project-name>

   Generates package.json, vite.config.ts, tsconfig.json, the widget script alias, and your first widget (prompts for name + description).

2. 2

   (Optional) add more widgets

   create already scaffolds your first widget. To add another:

   bun widget add

   Prompts for name and description, creates src/<name>/index.tsx and src/<name>/manifest.json.

3. 3

   Connect to a running Dash instance

   bun widget connect http://homeassistant.local:3123

   Builds, runs an OAuth device-code flow against your local Dash instance (not Hub), uploads each bundle to the Dash API under the local scope, enables dev mode, then watches src/ and re-uploads on save. Widgets refresh without reloading the page.

4. 4

   Publish

   bun widget publish

   publish runs login automatically the first time. See Publishing.

Project layout#

my-widgets/
├── package.json
├── vite.config.ts
├── tsconfig.json
└── src/
    ├── my-widget/
    │   ├── index.tsx          # Component + defineWidget
    │   └── manifest.json      # Widget metadata
    └── another-widget/
        ├── index.tsx
        └── manifest.json

One widget per directory under src/. Build outputs one self-contained JS bundle per widget plus a registry.json in dist/.

Mental model#

• The dashboard already handles: rendering, gestures, theming, entity subscriptions, settings forms, layout.
• Your widget supplies: how the bound entities are visualized, and what the primary tap action does.
• You do not write settings UI. Define a Zod schema; the dashboard renders the form.
• You do not manage WebSocket state. Read entities with useEntity / useEntities (from the ids the user picked in config) and the SDK keeps them reactive. useWidgetEntityGroup then aggregates them and supplies an empty state.
• You do not hold a Home Assistant connection or token. All reads and service calls go through SDK hooks and are checked against your declared capabilities.

Versions at a glance#

Auth flows: connect vs. login#

Two separate auth flows exist for two separate systems:

• bun widget connect runs an OAuth device-code flow against your local Dash instance. A browser opens to the Dash approval page. The token it issues is scoped to that Dash host and stored separately from Hub credentials.
• bun widget login runs an OAuth PKCE flow against GlassHome Hub (glasshome.app). A browser opens to Hub; the callback lands on http://127.0.0.1:9274/callback (or localhost). The resulting token is used for publish.

Where to go next#