Publishing widgets and tools
A widget or a tool you make is yours alone. To offer one to every Thingport instance, it goes into the Thingport repository by pull request, as a folder in the same layout as the examples: the metadata, the script, the HTML, a labels file per language, a README and a few screenshots. A maintainer reads the code before merging it, because it will run in other people’s Thingport instances with their access.
The steps and what reviewers look for are kept in one place each:
| Sharing a | Steps | What reviewers look for |
|---|---|---|
| Dashboard widget | Publishing to the community | Community widgets README |
| Tool | Tool development | Tools README |
In short, for either:
- Fork the repository and branch from
develop(contributing). - Put the folder under
community-widgets/<slug>/ortools/<slug>/. For a widget, Download for publishing in its ⋮ menu gives you the folder with a README to fill in. - Add screenshots of it at work, listed in its metadata, and list the slug in the folder’s
index.json. - Run the check that CI runs:
npx tsx scripts/validateCommunityWidgets.tsornpx tsx scripts/validateTools.tsinbackend/. - Open a pull request against
develop.
Once merged, a widget shows up under Community in every Thingport instance’s custom widgets, and a tool under
Administration → Tools, for an admin to install. Raise its version when you change it, and people who installed
it are offered the update.
A secret achievement
Section titled “A secret achievement”A published widget or tool can hide an easter egg that gives its users a secret badge: call
thingport.achievements?.unlock("<key>") when they find it (one of the community widgets has one). The badge
has to be in Thingport too, so the same pull request adds it: <slug>/<key> to SECRETS in
backend/src/services/achievementCatalog.ts, its entry in frontend/src/constants/achievements.ts (with its art in
frontend/src/components/achievements/), and its name, rule and stat under app.achievements.badges in every locale.
Feedback
Section titled “Feedback”Something unclear, wrong or missing on this page? Say so here, or react. It’s kept in GitHub Discussions. Something broken? Report it as a bug.