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×720

extension.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" }
}
  • schema must be 2.
  • id: at least two segments, lowercase letters, digits and dashes; spark.* and official.* are reserved; 64 characters max.
  • version: numeric x.y.z. name: 1 to 80 characters.
  • entry: an existing relative .js or .mjs file. style: an existing relative .css file.
  • icon: an existing relative .svg file, 32 KiB max. color: #rrggbb or #rgb; CSS names and rgb() are refused.
  • tileTypes: 1 to 20 types, each prefixed by <id>., unique.
  • screenshots: 0 to 8 existing .webp, .png, .jpg or .jpeg files.
  • certification is refused in an imported package. summary is capped at 400 characters, description at 4,000.
  • Absolute paths, .., backslashes and symbolic links are refused. .git and node_modules are 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

LimitValue
Manifest256 KiB
Files400
Uncompressed size25 MiB
Directory depth8
Tile types20
Icon32 KiB
Screenshots8
Downloaded zip30 MiB
Registry index2 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
  → activation

A 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.1 and http://localhost are 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 provide version, url and sha256.
  • The backend only enforces schema: 1 and an extensions array; the front normalises entries and drops invalid ones.

Update

  1. The registry publishes a higher version.
  2. Check reloads the index.
  3. Update downloads the zip and verifies its checksum.
  4. The active extension is disabled, the new version installed, then reactivated.
  5. 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.