SignalOS Widgets

Updates & versions

Releases never change your app silently. The registry serves one current version per item; your lockfile remembers what you took; updating is an explicit, reviewable step.

The model

  • Every item carries a semver version; the build refuses a content change without a bump, so versions are always honest.
  • New pulls always get the latest - there is no version picker. Old versions stay reachable through git history (point the registry URL at a tag or commit instead of main).
  • signalos.lock.json records each pulled item's version and per-file hashes - that's how drift becomes measurable.

Detecting drift

shell
npx signalos diff
#  data-table    0.1.0 → 0.2.0   upstream-updated
#  metric-tile   0.1.0           locally-modified
#                ~ src/components/widgets/metric-tile/MetricTile.tsx

upstream-updated: the registry released a new version. locally-modified: your app edited its copy. Both can be true at once. Exit code is 1 whenever anything drifted - run it as a weekly CI cron and you'll never be surprised.

Taking an update

shell
npx signalos update data-table
  • Files you never touched are overwritten in place.
  • Files you customized keep your edits - the new version is written next to them as <file>.new for a manual merge. After merging, run npx signalos lock refresh <widget> to record the merged state as the new baseline.
  • Commit the result as a normal PR - updates are code review.

Releasing (registry authors)

In this repo, a release is four moves:

shell
# 1. edit the widget
# 2. bump "version" in its registry-item.json + add a CHANGELOG.md entry
pnpm build:registry     # 3. validates + refuses if you forgot the bump
git commit && git push  # 4. commit source + r/ + hashes; CI re-verifies

Next

CLI reference →

Every command, flag, and exit code.

Quickstart →

The pull flow from the beginning.