API guide
Public capability imports, ownership, errors, and resource lifetimes.
Import application APIs from @legendapp/spark/<feature>. The single SDK archive includes private implementation modules; applications should not install or deep-import them. Hooks, imperative operations, and public types share their capability entry point.
Capability entry points
| Public path | Responsibility | Guide |
|---|---|---|
/app | App context, events, activation, quit guards | Documents and lifecycle |
/app/documents | File/URL requests, recent history, document controllers and reload watches | Documents |
/windows, /windows/macos | Windows, displays, cursor, geometry, React roots, native macOS chrome | Windows |
/menus, /context-menu, /tray | Owned app menus, native popups and tray items | Menus |
/shortcuts, /global-shortcuts, /shortcuts/commands, /shortcuts/keyboard | Accelerators, command routing, persisted bindings and low-level keyboard events | Keyboard shortcuts |
/dialogs | Open/save panels, message dialogs and confirmation | Files and dialogs |
/files | Paths, directories, byte/stream/positional IO, watches, scanning, Trash | Files |
/settings, /settings/observable, /secure-storage | JSON settings, Legend State persistence and selected SecureStore methods | Settings |
/settings/window | Normal/virtualized settings-window composition and options | Native UI |
/clipboard, /links | Clipboard formats and external URLs/paths | Desktop integrations |
/drag-drop | Native drag sources and drop destinations with generic payloads | Drag and drop |
/notifications, /system | Permissions/local notifications, Dock/taskbar, login startup and power | Desktop integrations |
/processes | Child processes and app-supplied helper executables | Desktop integrations |
/sqlite, /webview | Spark-owned database and embedded browser contracts | Desktop integrations |
/audio, /auth-session | Async players/media sessions and prepared browser-auth sessions | Desktop integrations |
/updates | Native whole-app update status, initiation, preferences and events | Packaging and updates |
/ui, /ui/uniwind, /ui/classnames | Common native controls and optional styling integrations | Native UI |
/markdown, /html | Read-only rich text, controlled inputs, and editable previews | Rich text |
/ui/search, /ui/sidebar, /ui/split-view, /ui/swipe, /ui/glass, /ui/symbol | Specialized macOS views | Native UI |
/ai, /ai/codex | Installed AI CLI execution and optional macOS Codex supervisor | AI execution |
/contracts, /diagnostics | Shared error/availability/resource types and explicit diagnostic utilities | Shared contracts |
Support varies by platform. Check feature-specific availability, permissions, and platform limits.
Shared contracts
Spark-owned commands generally resolve void; data has explicit result types. Expected cancellation, veto, and nonzero process exit are results. Operational failures reject with SparkError; branch on code rather than parsing messages. cause retains underlying failures. Availability is advisory and separate from permissions.
Unknown option keys reject with E_UNSUPPORTED_OPTION, including unknown keys whose value is undefined. Promise operations reject validation failures; synchronous utilities throw. Omission leaves update fields unchanged; null only clears declared nullable fields. Check each operation's merge/replace rules.
Subscriptions expose synchronous remove(). Async registrations resolve to a handle with asynchronous remove(). Resource-specific cleanup uses close(), remove(), terminate(), or dismiss() according to its meaning. Stop observing when the owner ends, await required cleanup, and retain failed handles for supported retry. Concurrent cleanup joins rather than starting duplicate removals. Hooks handle late setup completions and expose cleanup-error callbacks where applicable.
Time is explicit: timeoutMs/Unix timestamps use milliseconds; audio positions and notification delays use seconds. File/process bytes are Uint8Array. Native paths, URLs, and base64 are distinct data forms.
Ecosystem boundaries
Spark owns the supported SQLite, WebView, audio, UI, and desktop contracts. Their backend objects stay private. Selected Clipboard, Linking, and SecureStore methods follow Expo semantics; that does not promise complete Expo-package compatibility.
Legend State observables, React Native, Runtimes, Uniwind, and other ecosystem libraries retain their own APIs. Use upstream imports for capabilities beyond Spark's subset and define resource ownership when mixing integrations.
Tooling and metadata exports
These are not application runtime capabilities:
| Paths | Use |
|---|---|
/config, /schema.json, /config-plugin, /expo-config | Typed configuration, schema and Expo composition |
/metro, /native | Metro and native discovery |
/runtime-entry, /metro-gate, /init-template | Generated-project runtime/bootstrap integration |
/cli | CLI executable entry |
/package.json | Package metadata |
For changes to older imports and contracts, see migration.
Contributors should follow the repository's API design rules when adding APIs or replacing backends.