DroppyKit 1.21.0

Build Droplets for Droppy.

A Droplet draws on the same surfaces Droppy's own features do, in SwiftUI, against this SDK.

A Droplet is an extension that lives inside Droppy. It draws on the same surfaces Droppy's own features do — the notch, the shelf, the lock screen — and it is written in SwiftUI, against this SDK.

Droplets are native code running in Droppy's process, so the Store is review-and-sign: you build against DroppyKit, open a merge request on the Store repository (gitlab.com/droppyformac1/droplets, one folder per droplet), and the merged commit is built, signed and published by its pipeline. No droplet ships without someone having read it. By default, Droppy runs an unsigned one, such as the droplet you are building, after the person whose Mac it is approves that exact build, and asks them again each time Droppy opens. Don't ask again for local droplets turns off these questions for all local builds, including new and changed ones. Turn Ask before running local droplets back on in Settings, Store, Local droplets to restore the questions. Bundle validity checks still apply.

The surfaces you can build

SurfaceWhat it isProtocol
Shelf widgetA card on the expanded shelf, alone or sharing the rowShelfWidgetProviding
Live activityA compact row beside the notch, plus its expanded detailLiveActivityProviding
Expanded surfaceA takeover on the notch, for something that needs the roomExpandedSurfaceProviding
Settings paneYour droplet's own page inside Droppy's SettingsSettingsPaneProviding
HUDA transient message on the notchHUDPresenting
Lock screen rowOne line on Droppy's lock surfaceLockScreenStatusProviding
Menu bar extraA tile in Droppy's Command Center, the panel under its menu bar iconMenuBarExtraProviding
URLsdroppy://droplet/<id>/…, the reply channel for an app you driveDropletURLHandling
Tools for AI appsActions Claude, Cursor or Codex can run through Droppy's MCP serverMCPToolProviding

You pick the ones you need. A droplet that only draws a shelf widget is a perfectly good droplet.

What a droplet is made of

  • A Swift package that builds a dynamic library and links DroppyKit.
  • A droplet.json manifest — see DropletManifest — naming the droplet, the surfaces it provides, the capabilities it needs, and who made it.
  • An Icon Composer document named in icon. Jordy designs it for every Store droplet; your package carries a placeholder. See The icon.
  • A creator avatar, also required, which is the round mark beside your droplet's name in the Store. See DropletCreatorAvatar.

Trying it without installing anything

DroppyKitHarness opens your droplet in Droppy's Settings panel — the real one, built from the app's own source — with a page per surface, a switch per capability, and a running list of everything your droplet asks the host to do. It never touches the system, so it runs happily alongside Droppy itself.

import DroppyKit
import DroppyKitHarness

@main
struct WorldClockHarness: DropletHarnessApp {
    static func makeDroplet() -> any Droplet { WorldClockDroplet() }
}

Building it with a coding agent

Most droplets will be written with Claude Code, Codex or Cursor at the keyboard, and the SDK is built for that. Every scaffold carries the brief an agent reads before it starts, and the DroppyKit MCP server hands it the whole loop as tools: the build, the checks, pictures of every surface it can look at, a JSON verdict, and an install into Droppy Playground that says whether the bundle loaded. See Build with a coding agent.

Start here

Building a droplet

Artwork

Testing

Publishing

Entry point

Manifest

Host services

Design system

Versioning

Start here

Add the packageSwift Package Manager, Xcode, and why a bare swift build is wrong. Your first dropletFrom an empty folder to a droplet running in the harness. Build with a coding agentClaude Code, Codex and Cursor: the brief, the MCP server, and pictures an agent can look at. The manifestdroplet.json, the bundle it becomes, and the capabilities you declare.

Build a surface

Design guidelinesHow a droplet looks like part of Droppy instead of a guest in it. Good citizenSharing Droppy's process, the Mac's battery and the user's trust. Shelf widgetsA card on the expanded shelf, alone or sharing the row. Live activitiesA compact row beside the notch, and its expanded detail. Expanded surfacesA takeover on the notch, for something that needs the whole shelf. Settings panesYour droplet's own page inside Droppy's Settings. LaunchersDroppy's commands, droplets, settings and content, in a launcher you draw. Tools for AI appsYour droplet's actions in Claude, Cursor and Codex, through Droppy's MCP server. The iconJordy makes every Store icon; you make the creator avatar.

Test and ship

The harnessDroppy's real Settings panel, running your droplet, with nothing installed. Droppy PlaygroundA free, separate app: the real surfaces, the media player, and your droplets. Host supportWhich surfaces the shipping Droppy mounts, and what a refusal means. SubmittingReview, signing, and how a droplet reaches somebody's Mac.

Reference

API referenceEvery public type in DroppyKit, 172 of them.

Take it with you

Save the whole guideEvery chapter and the full API index in one page, ready to print or keep as a PDF.