Beside the notchLive activities: a symbol, a few words and a progress ring

LedgeKit 0.13.0

Build add-ons for Ledge

Describe what to show in Swift. Ledge draws it in the notch, the player, the menu bar and on the lock screen.

esc

LedgeKit is the Swift package Ledge add-ons are written with. An add-on gives Ledge a new ability without a new version of Ledge, and reaches people through the Add-on Store.

Where an add-on shows up

An add-on describes what it wants to show, and Ledge draws it in its own style, in the places below. The add-on never draws on screen itself, so everything looks like Ledge and stays where Ledge puts it.

XcodeFileEditThu 4:12
4:591
Dil MeraTalwiinder
2
Thursday 12 November3:34
5Timer4:38
6
Notes
Launch day12:41 Beta 2 goes out at 10:00
GroceriesYesterday Oat milk, eggs, basil
1Beside the notchLive activities: a symbol, a few words, a progress ring2In the playerButtons like Spotify's heart, a ••• menu entry, Playing Next3In the menu bar panelRows under Shelf, Clipboard and Settings4In SettingsThe add-on's own page, and widgets in the open notch5On the lock screenA pill under the clock while the Mac is locked6In the notchA tab of its own: lists, details and a Markdown editor

How an add-on works

An add-on is a folder ending in .ledgeaddon: a manifest, addon.json, that says who made it, what it shows and what it needs; an icon; and a native program built with LedgeKit.

While it's turned on, Ledge keeps the program running and talks to it over a session, one line of JSON at a time. The add-on sends what to show; Ledge sends back what the user did, and asks it questions, such as whether the playing song is in your Liked Songs. When the add-on needs something only Ledge has, like your Spotify sign-in, it asks Ledge, and Ledge does it without handing over the credentials.

The three pieces

What it isWhere
Add-on StoreThe page in Ledge's Settings that lists published add-ons, installs and updates themSettings → Add-on Store
LedgeKitThe Swift package add-ons are written with, and the ledgekit commandAmmyy9908/LedgeKit
LedgeAddOnsThe public repository of add-on source. Developers open pull requests here; merged add-ons are built and listed in the StoreAmmyy9908/LedgeAddOns

In the Store today

Add-onWhat it doesUses
Spotify LikesThe heart in Ledge's players likes or unlikes the playing Spotify songA player button, a settings page with Ledge's Spotify sign-in
Apple Music ControlsFavourite, Add to Playlist and Music's own Playing NextA player button, a ••• menu entry, Playing Next, a settings page
NotificationsMirrors visible macOS notification banners in the notchA settings page; Ledge reads the banners and passes their text

LedgeKit's repository also has an example, Timer, that uses every place in the figure above. The quick start builds a smaller version of it.

Where things stand

LedgeKit is a developer preview at version 0.13.0. Today:

  • The Store installs, updates and removes any published add-on, and checks each file against the catalogue first.
  • You can load a .ledgeaddon you built yourself from your Mac.
  • Add-ons can show everything in the figure above, keep their own settings and use accounts Ledge manages.
  • Building a package is still done by hand. ledgekit new, build and run are next.