Guides
Build, test and share
Build with the Vite plugin, load your widget in EdgeStation while you work, and ship it.
A widget built with the SDK goes from your source files to the dist/main.js EdgeStation loads through one Vite plugin. This page covers the build, loading the widget while you work on it, and shipping it.
The Vite plugin
import { widget } from '@edgestation/sdk/vite';
import { defineConfig } from 'vite';
export default defineConfig({ plugins: [widget()] });Add your framework's Vite plugin next to it, as in plugins: [react(), widget()]. widget():
- builds the entry into
dist/main.js: one ES module with every dependency bundled in, your framework's runtime included, - writes the CSS your code imports to
dist/main.css, - replaces
process.env.NODE_ENV, which React and Vue read and a browser lacks, with"production"(or"development"when you build with--mode development), - warns when
manifest.jsonis missing, isn't valid JSON, or doesn't point at the files it writes:mainshould bedist/main.js, andstylesshould bedist/main.csswhen there is CSS, - warns when a file of yours (not of your dependencies) calls
setTimeoutorsetInterval, which don't pause with the widget: useapi.afterandapi.everyinstead (see Timers at a glance).
It only applies to vite build. There is no dev server: EdgeStation loads the built files.
Options
| Option | Meaning |
|---|---|
entry |
The entry module, relative to the project root. Defaults to the first of src/main.ts, src/main.tsx, src/main.js and src/main.jsx that exists. |
widget({ entry: 'src/widget.ts' });Vite's own options still apply: build.outDir changes dist, for example (then point the manifest at the new folder).
Build
npx vite buildScripts in package.json save typing:
{
"type": "module",
"scripts": {
"build": "vite build",
"dev": "vite build --watch"
}
}Load it while you work
EdgeStation loads every folder of its widgets folder that has a manifest.json: %APPDATA%\com.edgestation.dashboard\widgets\ on Windows, ~/.local/share/com.edgestation.dashboard/widgets/ on Linux (Settings → Widgets → Installed → Open folder). Rather than copying your project there, link it once. On Windows, from a Command Prompt:
mklink /J "%APPDATA%\com.edgestation.dashboard\widgets\my-widget" C:\path\to\my-widgetOn Linux, from a terminal:
ln -s /path/to/my-widget ~/.local/share/com.edgestation.dashboard/widgets/my-widgetThe link's name, my-widget, is the widget's id. Then:
- In Settings → Widgets → Installed, click the Rescan button (the circular arrow): the widget shows under Installed.
- Add it to a page in Settings → Pages.
- Run
npx vite build --watch, which rebuilds on every change. - After each build, click Reload Edge at the bottom of the Settings sidebar to load it.
Rescan reads the widget folders again, so Settings shows a new widget or a changed manifest. Reload Edge reloads the Edge, which then loads each widget's latest build.
Share your widget
To share a widget, ship its folder with:
manifest.json,dist/(ormain.jsandstyles.cssfor a widget written by hand),- the icon, and any file the widget reads with
api.asset().
Leave out node_modules, src and the build configuration: EdgeStation doesn't use them. A zip of those files is enough. To install it, a user extracts the folder into their widgets folder (Settings → Widgets → Installed → Open folder), clicks Rescan, and adds the widget to a page.
Set version in the manifest, and minAppVersion to the EdgeStation version the widget needs.
Publish to the marketplace
Widgets in the marketplace show in Settings → Widgets → Marketplace, where a user installs one with a click. The marketplace is off until the user turns it on and accepts a warning; while it is off, marketplace widgets do not run. A new release never installs on its own: Settings → Widgets → Installed shows it, and the user installs it with Update or Update all. The list is widgets.json in the edgestation-widgets repository.
- Keep the widget in a public GitHub repository, with its
manifest.json, its icon and aREADME.mdat the root: Browse shows the icon and the README from your default branch. - Publish each version as a GitHub release with two files attached:
manifest.json, the widget's manifest,widget.zip, the files listed above, withmanifest.jsonat the root of the zip rather than in a folder.
- Raise
versionfor every release. EdgeStation installs a release when its version is higher than the installed one, and skips pre-releases. - Open a pull request on edgestation-widgets that adds
{ "id": "my-widget", "repo": "you/my-widget" }towidgets.json. The id becomes the widget's folder name and the key of every placement of it, so it can't change once listed.
EdgeStation reads the latest release's manifest.json to know whether there is a newer version, and downloads widget.zip only to install it. Browse shows how many times widget.zip was downloaded, all releases together, updates included.
This workflow builds the widget and publishes the release when you push a tag, such as git tag 1.2.0 && git push --tags:
name: Release
on:
push:
tags: ['*']
permissions:
contents: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 22
- run: npm ci
- run: npm run build
- run: zip -r widget.zip manifest.json dist icon.svg
- run: gh release create "$GITHUB_REF_NAME" manifest.json widget.zip --title "$GITHUB_REF_NAME"
env:
GH_TOKEN: ${{ github.token }}A widget is checked once, when it is added to the list, not at each release: every release you publish is offered to its users as an update, which they install from Installed. A widget taken off the list stops getting updates. A widget whose author turns against its users is banned instead: EdgeStation then deletes it from every machine, with its tiles and saved data, and tells the user why.
Settings shows each marketplace widget with the permissions it asks for and the GitHub account that owns its repository. A verified badge marks trusted accounts. The badge never comes from author in the manifest, because any widget can set that.
Working on the built-in widgets
The built-in widgets, in the repository's widgets folder, are Svelte 5 components built with the SDK the way a widget of your own is. Each is a pnpm workspace package, @edgestation/widget-<id>:
clock/
manifest.json ("main": "dist/main.js", no "styles")
package.json (build and dev scripts)
icon.svg
src/
main.ts
Clock.svelte
dist/main.js (built, not committed)They share one widgets/vite.config.ts. From the repository's root:
pnpm tauri devrebuilds the widgets whenever their source changes, andpnpm tauri buildbuilds them before bundling the app.pnpm --filter @edgestation/widget-clock buildbuilds one on its own.pnpm checktype-checks them.