Guides

The manifest

Every field of manifest.json, and the schema that checks it in your editor.

Every widget folder has a manifest.json. EdgeStation only lists folders that have one, and reads it to show the widget in Settings and to load it.

manifest.json
{
	"$schema": "./node_modules/@edgestation/sdk/manifest.schema.json",
	"name": "My widget",
	"version": "1.0.0",
	"description": "What it shows.",
	"author": "You",
	"minAppVersion": "0.1.0",
	"main": "main.js",
	"styles": "styles.css",
	"icon": "icon.svg",
	"size": { "w": 2, "h": 1 },
	"permissions": ["fetch"]
}

Fields

Only name is required. Paths are relative to the widget folder.

Field Meaning
name Required. The name shown in Settings.
version The widget's own version.
description What the widget shows, for Settings.
author Who made it.
minAppVersion The oldest EdgeStation the widget runs on, as major.minor.patch. See below.
main The entry ES module. Defaults to main.js; dist/main.js for a widget built with the SDK.
styles A stylesheet loaded into the widget's shadow root; dist/main.css when the SDK build writes one.
icon An image shown next to the widget in Settings. See below.
size { "w", "h" }: the default size in grid cells when the widget is added to a page. Whole numbers, at least 1.
settings Options the user sets for each placement. See Settings.
permissions The parts of the api the widget uses, such as ["media", "fetch"]. See below.
$schema Only for editors: the JSON Schema that checks this file. EdgeStation ignores it.

The widget's id is not in the manifest: it is the name of its folder. The widget reads its own manifest in api.manifest, with id set.

minAppVersion

minAppVersion is the version of EdgeStation whose api the widget uses. An older app shows the widget's error card, saying which version it needs, instead of loading the widget and letting it fail on a missing api member.

With the SDK, set it to the SDK version you build with: the two are released together. The 0.1.0 in the examples of these pages is only a placeholder.

permissions

Six members of the api reach the machine or the web, and a widget must ask for each one it uses:

Permission Gives
system api.system() and api.topPrograms()
media api.media
apps api.apps
audio api.audio
fetch api.fetch
webview api.webview, and a Profile choice in the widget's settings

The other members (storage, every, loading, ...) only touch the widget itself, so they need nothing. A manifest without permissions gets none.

Calling a member the manifest doesn't list throws, and shows the widget's error card: it tells the user that the widget needs an update. The error in the console names the permission to add.

When the user clicks Install in Browse, a dialog lists what the widget will be able to do, one short sentence per permission, and asks them to confirm. A new version that asks for more permissions does the same with only the new ones: Update all skips it, and it waits for the user to click its own Update button. A widget that asks for no permissions installs with no dialog. Built-in widgets and widgets dropped into the widgets folder show no dialog.

Permissions tell the user what a widget means to use. They are not a sandbox: widgets run inside the Edge page itself, so install only widgets you trust.

icon

A square SVG or PNG on a transparent background. Only its shape counts: Settings draws it in the accent color, like the icons of the built-in widgets. Without one, the widget gets a puzzle piece.

The schema

The SDK ships a JSON Schema for the manifest. Point $schema at it and editors such as VS Code complete the fields as you type, show what each one means, and flag mistakes: a missing name, a misspelled field, a select setting without options.

{
	"$schema": "./node_modules/@edgestation/sdk/manifest.schema.json"
}

The path is relative to the manifest. The schema is also exported as @edgestation/sdk/manifest.schema.json, for tools that validate manifests themselves.