@glasshome/widget-sdk
SDK for building GlassHome dashboard widgets with SolidJS.
Provides defineWidget, reactive entity bindings, framework components/hooks, a Vite plugin for widget development, and Tailwind v4 source paths — everything you need to build, preview, and ship widgets for GlassHome, the local-first dashboard for Home Assistant. Start with the widget development guide.
Install
npm install @glasshome/widget-sdk solid-js
# or
bun add @glasshome/widget-sdk solid-js
solid-js ^1.9.11is a required peer dependency.
Subpath Imports
@glasshome/widget-sdk — SDK API
Core widget API: define widgets, create reactive entity bindings, and use framework components/hooks.
import { defineWidget, createEntity, SDK_VERSION } from "@glasshome/widget-sdk";
const entity = createEntity("light.living_room");
export default defineWidget({
manifest: {
tag: "glasshome-my-widget",
type: "status",
name: "My Widget",
size: "small",
sdkVersion: "^0.1.0",
defaultConfig: { label: "Hello" },
},
component: (props) => <div>{props.config.label}</div>,
});
Small values a widget keeps across reloads (recent picks, the last tab) go through useWidgetState(key, schema, fallback), kept by the host for this widget and this person. localStorage is in memory and empty after a reload.
@glasshome/widget-sdk/vite — Vite Plugin
Vite plugin for widget development. Handles widget bundling, preview server, and registry generation.
// vite.config.ts
import { defineConfig } from "vite";
import { glasshomeWidget } from "@glasshome/widget-sdk/vite";
export default defineConfig({
plugins: [glasshomeWidget()],
});
The plugin accepts an optional entry option (defaults to "src/index.tsx"):
glasshomeWidget({ entry: "src/my-widget.tsx" });
@glasshome/widget-sdk/tailwind-sources — Tailwind v4 CSS Source
Provides a @source directive for Tailwind v4 so the compiler scans widget SDK source files for class names.
/* In your widget's CSS entrypoint */
@import "tailwindcss";
@source "@glasshome/widget-sdk/tailwind-sources";
Dark mode
Style with Tailwind's dark: variant and the theme variables (var(--foreground), var(--card)): they follow the home's mode in every engine and every SDK version. For logic, call isDark(); inside a memo or effect it runs again when the home switches mode. matchMedia("(prefers-color-scheme: dark)") answers the device's setting, which differs from the home's mode when the home follows a schedule or the sun.
import { isDark } from "@glasshome/widget-sdk";
import { createMemo } from "solid-js";
const palette = createMemo(() => (isDark() ? DARK_COLORS : LIGHT_COLORS));
Escape patterns, when widgets own their visual surface
Most widgets route through the channel API: <Widget tone> / <Widget color colorTo> / <Widget.Icon color>. A small number of widgets intentionally own their entire visual surface and bypass the channel. These are supported escape patterns, not anti-patterns.
Weather, full-background scenes
The weather widget renders a <WeatherBackground condition> component that replaces the shell gradient entirely with an animated per-condition scene (sunny rays, rain droplets, snow particles). Channel vars do not apply to the shell; Widget.Icon color still receives a CSS string per condition for the icon badge.
Media-player, vinyl gradient
The media-player widget composes a custom <VinylRecord> element with an album-art radial overlay. The visual identity is content-driven (album artwork) rather than tone-driven; the channel base color stays neutral underneath.
Area, per-metric pill colors
The area widget renders quick-glance metric pills (CO2 traffic-light, humidity range, temperature) where each pill's color encodes the metric's semantic state (CO2 green/amber/red, humidity dry/comfortable/humid). These per-metric color rules are intentionally semantic-per-metric, not channel-driven, and live in the widget's own helpers.
If your widget needs full visual control (a chart, a video stream, a custom animated surface), follow these patterns: keep the <Widget> shell neutral (no tone/color), place your custom DOM inside <Widget.Content>, and document the choice in the widget's README.
Troubleshooting
| Variable | Effect |
|---|---|
GLASSHOME_WIDGET_NO_WORKER | Set to 1 to make bun widget connect check each rebuild in a fresh process again, instead of reusing one worker for the session. |
Peer Dependencies
| Package | Required | Notes |
|---|---|---|
solid-js | Yes | SolidJS reactive primitives and JSX runtime |
License
MIT