addon.json
The manifest names the add-on, describes it in the Store, says what it needs, and tells Ledge which file to run.
Fields
| Field | Required | Rules |
|---|---|---|
id | Yes | Permanent. 1 to 64 characters of lowercase letters, digits and hyphens. Never change it after publishing. |
version | Yes | Three whole numbers separated by dots, like 1.0.0. |
protocolVersion | Yes | Must be 1. |
name | Yes | The name shown in the Store and Settings. Can't be blank. |
summary | Yes | One line under the name in the Store. |
description | Yes | A longer description of what it does. |
author | Yes | Who made it. Shown when Ledge asks you to trust the add-on. Can't be blank. |
capabilities | Yes | A list with no repeats, from the capabilities below. |
executable | Yes | The file name of the program inside the package. No folders, slashes or control characters. |
icon | No | A PNG in the Assets folder, written Assets/Icon.png. Without it, Ledge uses a standard icon. |
Capabilities
A capability is something an add-on asks Ledge for. Ledge rejects a manifest that names one it doesn't know.
| Capability | What Ledge provides |
|---|---|
spotify-library | A short-lived Spotify access token with library read and write access, and the ID of the Spotify song that's playing. Ledge draws the heart in the player and the add-on's settings page. |
notification-banners | In development. The title and body of a visible macOS notification banner, and whether previews are on. Ledge shows the text the add-on returns in the notch. |
The icon
A real PNG, no larger than 2048 by 2048 pixels and 4 MB. Packages published to the Store must include Assets/Icon.png, and you must own the rights to it or have permission to use it.
Writing it from Swift
AddOnManifest is the same type Ledge reads. You can build one, validate it and encode it, rather than writing the JSON by hand:
import Foundation
import LedgeKit
let manifest = AddOnManifest(
id: "my-addon", version: "1.0.0",
name: "My Add-on", summary: "One line for the Store",
description: "A sentence or two about what it does.",
author: "Your name", capabilities: ["spotify-library"],
icon: "Assets/Icon.png", executable: "MyAddOn")
try manifest.validate()
let json = try JSONEncoder().encode(manifest)Validation errors
validate() throws a ManifestValidationError, and the CLI prints the same message:
| Error | Message |
|---|---|
invalidField(name) | Invalid manifest field: name. |
unsupportedProtocol(n) | Unsupported protocol version: n. Supported: 1. |
unsupportedCapability(c) | Unsupported capability: c. |
The manifest check doesn't look at files. When Ledge loads a package, it also checks that the executable exists and can run, that nothing is a symbolic link, and that the icon is a valid PNG.