Packages and registries
A package is a folder or a zip with a manifest, a script and optional assets. A registry is a static JSON index pointing at zipped versions. Nothing is installed automatically.
Package layout
extension.json
index.js # classic script, not an ES module
style.css # optional
icon.svg # optional, used as a tinted mask
media/1.webp # optional captures, 16:9, 1280×720extension.json
{
"schema": 2,
"id": "demo.hello",
"name": "Hello",
"version": "0.1.0",
"subtitle": "Demo tile",
"summary": "Shows a message in a tile.",
"description": "Optional long description.",
"category": "Demo",
"icon": "icon.svg",
"color": "#769ac8",
"entry": "index.js",
"style": "style.css",
"tileTypes": ["demo.hello.tile"],
"screenshots": ["media/1.webp"],
"engine": { "spark": ">=0.1" }
}schemamust be2.id: at least two segments, lowercase letters, digits and dashes;spark.*andofficial.*are reserved; 64 characters max.version: numericx.y.z.name: 1 to 80 characters.entry: an existing relative.jsor.mjsfile.style: an existing relative.cssfile.icon: an existing relative.svgfile, 32 KiB max.color:#rrggbbor#rgb; CSS names andrgb()are refused.tileTypes: 1 to 20 types, each prefixed by<id>., unique.screenshots: 0 to 8 existing.webp,.png,.jpgor.jpegfiles.certificationis refused in an imported package.summaryis capped at 400 characters,descriptionat 4,000.- Absolute paths,
.., backslashes and symbolic links are refused..gitandnode_modulesare skipped.
Icon and tint
The icon is a CSS mask, never interpreted markup: the SVG provides the alpha, the colour comes from currentColor. No script in the file runs, and the icon takes the extension's colour in the Store, the rail and the tab bar.
Consequence: Spark cannot re-apply a stroke width. Draw the SVG in a 24 viewBox withfill="none", stroke="currentColor", stroke-width="1.7", and check it at 16 px.
Bundle
(function () {
const extensions = (window.SparkExtensions = window.SparkExtensions || {});
extensions["demo.hello"] = function (runtime) {
const React = runtime.React;
function HelloTile() {
return React.createElement("div", null, "Hello");
}
return {
activate(api) {
api.tiles.register({
type: "demo.hello.tile",
title: "Hello",
view: HelloTile,
});
api.commands.register({
id: "demo.hello.open",
title: "Open Hello",
tileType: "demo.hello.tile",
run: () => api.tabs.openTile("demo.hello.tile"),
});
},
};
};
})();- The host exposes
window.SparkRuntime = { React, jsxRuntime }and passes the same runtime to your factory. - Never import React as a bare module: use the host runtime.
- The package has no dedicated Tauri API. It shares the main window and its global APIs.
Limits
| Limit | Value |
|---|---|
| Manifest | 256 KiB |
| Files | 400 |
| Uncompressed size | 25 MiB |
| Directory depth | 8 |
| Tile types | 20 |
| Icon | 32 KiB |
| Screenshots | 8 |
| Downloaded zip | 30 MiB |
| Registry index | 2 MiB |
Install
registry_fetch(url)
→ download zip (30 MiB max)
→ compare SHA-256
→ bounded extraction
→ validate extension.json
→ staging → extensions/<id>/<version>/
→ extensions.json (version, path, source)
→ ExtensionManager.addEntry
→ activationA download, checksum, extraction or manifest error leaves the previous installation intact. State is written to extensions.json with version,path and source (absent for a local import). A new version goes into a new folder; the old folder is not deleted automatically.
Registry index
{
"schema": 1,
"name": "My registry",
"updatedAt": "2026-11-21T22:00:00Z",
"extensions": [{
"id": "demo.hello",
"name": "Hello",
"publisher": "Demo",
"summary": "One line about the extension.",
"category": "Demo",
"versions": [{
"version": "0.3.0",
"url": "https://…/hello-0.3.0.zip",
"sha256": "…",
"size": 1307,
"engine": ">=0.1",
"publishedAt": "2026-11-21T22:00:00Z"
}]
}]
}- A source is an HTTPS URL to a static JSON file. Up to 20 sources, saved in
extensions.json. - In release, only HTTPS is accepted; in debug,
http://127.0.0.1andhttp://localhostare allowed. - Indexes are not cached on disk: refresh reloads them, a restart asks again.
- The latest version is chosen by numeric comparison of
x.y.z. A version must provideversion,urlandsha256. - The backend only enforces
schema: 1and anextensionsarray; the front normalises entries and drops invalid ones.
Update
- The registry publishes a higher version.
- Check reloads the index.
- Update downloads the zip and verifies its checksum.
- The active extension is disabled, the new version installed, then reactivated.
- Tiles and extension state are preserved.
There is no automatic installation and no stable/beta channel yet. Built-in extensions are never updated from a registry.