write-widget

Writing an n-dashboard widget

A widget is one function on disk. The platform decides when to call it (clock, MQTT message, webhook, manual), validates what it returns against its kind's schema, and pushes the result to open tabs over SSE. There is no plugin format and no config-driven renderer, so summing a field, joining two APIs and remembering what you already saw are all ordinary code.

Read these first, in this order

Do not write a widget from memory of this file — the API is defined in the repo and this skill can drift from it.

1. src/shared/ctx.d.ts — the single source of truth for Ctx and for every kind's data type. Read the type you are about to return, in full.

2. src/shared/kinds/<kind>.ts — the runtime Zod schema, the sample and the starter template for that kind. The schema is what actually rejects a result.

3. The closest examples/*/widget.ts — each one exists to teach a specific part of the API and is heavily commented. Pick by what you need:

   need	example
   HTTP JSON → one number	crypto-price
   an API key	stock-quote
   summing / reshaping an array	api-sum
   MQTT, plus recorded history	office-temp
   reading history back as a chart	temp-history
   GraphQL (and why res.ok is not enough)	github-prs, github-approvals
   a webhook and a poll in one widget	slack-unread
   signed JWT + a token cached in ctx.state	bigquery-query
   Google Calendar (same code on either auth path)	next-meetings
   threshold bands	disk-usage
   HTTP Basic + asking an API for fewer fields	jira-jql

The two files

data/widgets/<id>/
  widget.json      config — kind, triggers, history, timeout
  widget.ts        the function
  state.json       ctx.state, written back after each successful scheduled run
  history.ndjson   append-only, trimmed to the retention window

widget.json, validated by widgetConfigSchema in src/shared/widget.ts: