Publishing Widgets

Share your widgets with the GlassHome community by publishing them to Hub.

Publish Flow

1. 1

   (Optional) Log in to GlassHome Hub

   You only need to run this explicitly if you want to authenticate before publishing. The publish command auto-runs login if no token is found, so this step is optional in practice.

   bun widget login

   This runs an OAuth PKCE flow against Hub. A browser opens; the callback lands on http://127.0.0.1:9274/callback. The resulting token is stored locally and reused on subsequent publishes. This is separate from bun widget connect, which authenticates against your local Dash instance using a device-code flow.

2. 2

   Validate your widgets

   Checks manifests, bundle sizes, and SDK version compatibility. Fix any issues before publishing.

   bun widget validate

3. 3

   Publish

   The CLI validates first, then prompts you to select which widget to publish, choose a scope, and pick a version bump. It then builds and uploads the bundle to Hub via a presigned R2 URL.

   bun widget publish

   Use flags to skip prompts:

   • --name <widget>: publish only the named widget.
   • --bump keep|patch|minor|major: pre-pick the version bump. This updates the version field in src/<name>/manifest.json.
   • --scope <scope>: pre-pick the publishing scope.

Publish lifecycle

The gate checks in the diagram above are enforced server-side, with precise failures:

• Bundle > 2 MB → rejected with 400.
• Duplicate version → 409; published versions are immutable.
• Scope you don’t own → rejected. Org scopes require the owner or admin role.

Versioning

The version field lives in src/<name>/manifest.json. The --bump flag increments it automatically. Versions follow semver:

• Patch (0.1.0 → 0.1.1). Bug fixes, no config changes.
• Minor (0.1.0 → 0.2.0). New features, backward-compatible config.
• Major (0.2.0 → 1.0.0). Breaking config changes (bump configVersion too and add a migrate function; see Config Migrations).

Publishing Scopes

When you publish, the CLI prompts you to select a publishing scope if you belong to any organizations:

? Select publishing scope:
  ❯ @your-username (personal)
    @my-team (organization)

Your personal scope is your username (@username). Organization scope uses the org slug. You can create organizations on GlassHome Hub. The CLI learns which scopes you can publish to from GET /api/widgets/scopes, which returns your personal scope plus any org scopes you have permission to publish under.

How your username is determined

Your username is assigned automatically at signup by slugifying your display name (lowercased, with non-alphanumeric runs collapsed to dashes, so “Alice Test” becomes alice-test). It is unique per account: if someone already has that slug, later accounts get a numbered suffix (alice-test-2).

The username is decoupled from your display name. Renaming your display name later does not change your scope, so widgets you have already published stay reachable at the same @username/widget-name ID.

You can change your username in your account dashboard settings, but not while you have widgets published under your current scope (changing it would orphan them). Yank or remove those widgets first, or publish future versions under a new scope.

@glasshome is the reserved official scope and cannot be claimed by users or organizations.

Yank, deprecation, and release notes

The database schema tracks yanked, yankedReason, deprecationMessage, and releaseNotes per version. There is no user-facing mechanism to yank or deprecate a version yourself yet. If you publish a broken version and need it pulled, contact me directly and I’ll yank it.

releaseNotes will be shown in the widget detail view once that UI is built.

After Publishing

Your widget appears in the Widget Browser, installable in one click. To ship an update, bump the version and run publish again.

If your widget declares examples, its preview images are produced for this version and appear on its Hub page and in the Widget Browser. See Widget Previews.

Trust Badges

• Official. Maintained by GlassHome. Installed without a confirmation dialog.
• Community. Published by users. Users see a consent dialog before installing.