Developer mode and the dev kit
Turn on developer mode to scaffold widgets, get typed autocomplete from the generated dev kit, reload from the tray, and inspect running widgets.
Developer mode is the switch between using DeskDash and building for it. It lives in Settings, General: "Developer mode: tools for writing your own widgets." It takes effect immediately, and it changes nothing about how widgets run; it only reveals the tooling around them:
- the Developer settings page,
- error badges on widgets that report errors,
- Inspect in a widget's right-click menu.
Off (the default), none of that exists, so regular users never see a stray badge or a debug menu.
The Developer page
Four sections, top to bottom:
New widget. A name and a folder id (auto-suggested from the name), and Create widget writes a working widget folder plus its dev kit into your widgets directory. That scaffold is the starting point of the tutorial.
Widgets folder. Shows where widgets load from, with Reload (the
same rescan as the tray's Reload widgets) and Open to jump there in
Explorer. The default location is Documents\DeskDash\widgets; changing it
is a general setting, under Settings, General, Content, since it moves
themes too.
Dev kit. Refresh all regenerates every widget's dev kit, and
Add to a folder... writes a kit into a widget folder you already have
(it must live in the widgets folder and contain a manifest.json).
Debugging. The Developer tools button, though the right-click Inspect on a widget is usually the shorter path.
What the dev kit is
The kit is a generated .deskdash/ folder (plus one jsconfig.json beside
the widget) whose only job is making your editor understand the widget:
| File | What it gives you |
|---|---|
deskdash.d.ts and sdk/ | the dd global: autocomplete for the whole SDK, hover docs, go-to-definition, and a typo is an error |
settings.d.ts | DdSettings, generated from your own manifest.json, so your settings keys autocomplete with the right types |
dd-tokens.css | every --dd-* design token with its default value, for CSS autocomplete |
manifest.schema.json | manifest completion and validation, wired by the $schema line the scaffolder writes |
jsconfig.json | ties it together; written only if absent, so your edits to it survive |
Everything under .deskdash/ is generated and disposable: nothing reads it
at runtime, deleting it changes nothing but your autocomplete, and
published widgets leave it out entirely.
It stays fresh on its own where it matters: settings.d.ts regenerates on
every widget reload, so editing the manifest and reloading is enough to get
the new setting typed. The rest of the kit tracks the app, not your widget;
after a DeskDash update, press Refresh all once to pull the new SDK
types and tokens.
The edit loop
There is no watcher and no build step; the loop is: edit, Reload widgets (tray right-click, or the Developer page's Reload), look. The reload rescans the widgets and themes folders and remounts every widget, and widget files are served uncached, so what you saved is always what runs.
When a widget throws an uncaught error or logs one through
dd.log("error", ...), it keeps running but gains a red badge carrying the
message; the full text also lands in the app log with the widget's id. A
widget that stops responding entirely (a blocked main thread, an infinite
loop) is a different state: it gets replaced by a "stopped responding"
overlay, retried once automatically, then waits for a manual reload.
Inspecting
Right-click a widget, Inspect. Widgets are frames inside the desktop's webview, so one inspector covers all of them: pick your widget's frame from the console's context dropdown and you have its console, DOM, and network view (which will be quiet, by design). CSS changes made live in the inspector behave like in any browser; they last until the next reload.
What a widget is
The mental model: a folder of plain HTML, CSS, and JavaScript in an isolated frame, a manifest that declares everything, and the dd SDK as the only door to the system.
Your first widget
A start-to-finish tutorial that builds a small clock widget: scaffold, manifest, markup, live time, and the reload loop.