@glasshome/widget-sdk

中文文档
1.32.3发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 3628

SDK for building GlassHome dashboard widgets with SolidJS

原始使用文档
文档目录13 节
  1. Install
  2. Subpath Imports
  3. @glasshome/widget-sdk — SDK API
  4. @glasshome/widget-sdk/vite — Vite Plugin
  5. @glasshome/widget-sdk/tailwind-sources — Tailwind v4 CSS So…
  6. Dark mode
  7. Escape patterns, when widgets own their visual surface
  8. Weather, full-background scenes
  9. Media-player, vinyl gradient
  10. Area, per-metric pill colors
  11. Troubleshooting
  12. Peer Dependencies
  13. License

@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.11 is 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

VariableEffect
GLASSHOME_WIDGET_NO_WORKERSet 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

PackageRequiredNotes
solid-jsYesSolidJS reactive primitives and JSX runtime

License

MIT

版本与发布记录

@glasshome/widget-sdk 共发布 81 个版本,首次发布于 2026/03/23;过去 12 个月发布了 81 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.32.3latest2026/11/16今天
1.32.22026/11/151 天前
1.32.12026/11/0610 天前
1.32.02026/11/0610 天前
1.31.12026/11/0610 天前
1.31.02026/11/0610 天前

关于 @glasshome/widget-sdk 的常见问题

@glasshome/widget-sdk 是什么?

SDK for building GlassHome dashboard widgets with SolidJS

如何安装 @glasshome/widget-sdk?

在项目目录运行 npm install @glasshome/widget-sdk,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:solid-js(^1.9.11)、@glasshome/ui(1.37.0)、@glasshome/sync-layer(0.9.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@glasshome/widget-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@glasshome/widget-sdk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@glasshome/widget-sdk 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@glasshome/widget-sdk 可以商用吗?

@glasshome/widget-sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@glasshome/widget-sdk 的下载量有多少?

根据 npm 官方下载统计,@glasshome/widget-sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,628 次,日均约 121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@glasshome/widget-sdk 还在维护吗?

最新版本 1.32.3 发布于 2026/11/16(今天);至今共发布 81 个版本,其中过去 12 个月发布了 81 个;首次发布于 2026/03/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。