Package and share

Two kinds of extension can be handed to another person today: a custom widget (a folder) and a theme (a file). A plugin ships inside the app itself.

Not supported yet

Installing a third-party plugin into a released TeamHUD is not supported. There is no plugin installer, package format or registry. The only way a plugin reaches people is by being built into the app. This page says so plainly so you do not look for a button that is not there.

Share a custom widget

A custom widget is a folder with a widget.json and an index.html. See Build your first custom widget to make one.

1. Check the folder. It contains widget.json, your HTML, an icon.svg for the hub button, and any scripts, styles or images it uses. Remove build.lock if it exists; that file is reserved.

2. Zip the folder. Zip the widget’s own folder so the zip holds one top-level folder, for example my-widget/.

3. Send it. Any way you like.

4. The other person unzips it into their widgets folder: .teamhud/custom-widgets/ in their home folder (%USERPROFILE%\.teamhud\custom-widgets on Windows). TeamHUD watches that folder, so the widget appears without a restart.

5. They approve it. A widget they did not write shows a Needs approval badge in Preferences, Plugins. It lists every permission the widget asks for, each marked Required, Optional or Every widget. Allow approves the list, Don’t install declines it. The widget cannot be switched on before then. If you later ship a version that asks for more, it shows Wants more access and asks again.

List what the widget needs in widget.json under permissions, and ask for as little as possible. People are wary of network access and of acting as them. See Custom widgets for what each permission means to the person using it.

For a team, you can also keep the widget in a git repository and clone it into .teamhud/custom-widgets/. Developers working in the TeamHUD repository can use its own custom-widgets/ folder instead.

Share a theme

A theme is one file: teamhud-theme-<name>.json, holding the look and, if you choose, your own wallpapers, backdrop shaders and sound packs.

1. In Preferences, Appearance, find your theme under My themes and choose Export.
2. Tick the assets to include. Sounds you recorded yourself stay out unless you tick them.
3. Send the file.
4. The other person chooses Import… under Backup: Appearance file. The theme shows as an imported theme with Dismiss, Save to My themes, Apply now and Save and apply, and they can untick bundled assets they do not want.

A theme file carries looks only. Window positions travel in a full appearance backup, not in a theme. See Appearance and the theming reference.

How a plugin ships today

A plugin is a package under plugins/ in the TeamHUD repository, listed in apps/desktop-lite (see Build your first plugin). It reaches people in a release of the app:

pnpm make        # builds every package, the plugins and the renderer bundles, then packages the app

make runs build:all, which includes build:plugins and build:component-bundles:prod, so the plugin’s code is inside the installer. People get it by updating TeamHUD. To get a plugin into a release, contribute it to the repository. See Contribute to TeamHUD.

If you need something installable today with no release, use a custom widget. It cannot do everything a plugin does: it has no data subscriptions beyond the permissions it can be granted, and no access to the main process.

What’s missing

Planned, not built. This is the work to make a plugin installable by someone else:

• A plugin package format and a signed install path in the app.
• An install and approval prompt like the one custom widgets have.
• A way to list and remove installed plugins.

Until then, treat “plugin” as “contribution to TeamHUD itself”.

If it goes wrong

• The widget does not appear. The folder is not directly under .teamhud/custom-widgets/, or widget.json is missing or invalid (the hub icon must be an .svg).
• It appears but is greyed out. It is waiting for approval in Preferences, Plugins.
• A theme import shows nothing new. The file is not a TeamHUD theme file (it must have "kind": "teamhud-theme").