Upgrading Spark
Update Spark, review migrations, and move older prototypes to the current APIs.
Upgrade an app
Commit your app and lockfile first. Record the old version from .spark/version, or the installed Spark package if that file is missing.
npx --no-install spark upgrade --dry-run
npx --no-install spark upgrade
npx --no-install spark doctorThe dry run lists dependency pins, file changes, and manual steps. Upgrade installs matching SDK archives and applies migrations in version order. It keeps your package manager and updates its settings and overrides. Keep spark-packages/ and those settings in version control; do not replace patched archives with upstream packages.
Read node_modules/@legendapp/spark/skills/spark/UPGRADING.md from the newly installed package for every version between the old and new releases. Complete .spark/upgrade-notes.md, then run your app's typecheck and tests. Rebuild custom development runtimes after native changes. If installation fails, fix the cause and retry; partial edits may remain.
Move from a preview to 0.0.1
spark upgrade stays on the installed release's channel: previews use next, stable releases use latest. To switch an npm app to 0.0.1 after it is published:
npm install --save-exact @legendapp/spark@0.0.1Use your package manager's equivalent install command, then run the upgrade and doctor commands above. Preserve the old version record until migration finishes. Review the installed notes and test your app. For a new release with pnpm 12, see the release-age option.
Changes since next.5
- next.6 repaired the creator package; existing apps need no source migration.
- next.7 added creator release-selection flags. These apply when creating apps, not to
spark upgrade. - Yarn PnP can run the creator; generated native apps use
node_modules. - Dependency fixes preserve pnpm settings and patched Nitro peers, repair Enriched HTML web dependencies, and keep Fast Refresh working when imports are removed and re-added.
Older prototypes
Older prototypes need import and contract changes. Removed exports have no aliases. Rebuild matching native runtimes after updating.
Import changes
| Removed path | Current path |
|---|---|
/message-dialog | /dialogs |
/windows/react, /windows/managed, /windows/controls | /windows |
/app/exit | /app |
/app/recent-documents | /app/documents |
/files/scanner, /files/watchers, general /settings/paths helpers | /files |
/shortcuts/commands/storage | /shortcuts/commands |
/settings/window/options | /settings/window |
/processes/commands | /processes |
/drag-drop/views | /drag-drop |
/ui/select-controls | /ui |
/expo-metro, /universal | /metro |
All paths use the @legendapp/spark prefix. The singleton /global-shortcuts/hotkeys interface was removed; use owned accelerator registrations or explicit keyboard APIs. Application-specific music drag payloads and chrome presets belong in app code.
Behavior changes to review
- Windows: pass explicit IDs; use unified open options/results, display-relative outer-frame geometry, instance-bound listeners/guards, and grouped
macoschrome. Animate throughsetWindowBoundsin/windows. - Documents/app: use typed file/URL requests with bounded replay; quit/close approval belongs in async guards. Save before approving shutdown.
- Dialogs/files: branch on cancellation discriminants; message buttons use IDs and checkbox state is optional. File dialogs use
defaultPathand extension filters. Copy/move require explicit overwrite; file watches invalidate rather than report an exact change journal. - Settings: validate persisted values with decoders. Observable factories are async and expose readiness,
value$,error$, flush and close. General paths/IO moved to files. - Clipboard/secure storage: use selected Expo-shaped methods; duplicate facades were removed. Clipboard string writes return a boolean, secure missing reads return null.
- Menus/system/tray: use typed items appropriate to each surface and owned create/update/remove registrations. Unsupported item shapes reject before publication.
- Notifications/updates: separate content/trigger and pending/delivered operations. Native update checking acknowledges initiation; typed events report later progress.
- Processes/audio/auth: retain owned resource handles, explicit result states, byte IO, cleanup and supported cancellation. Audio hooks return loading/ready/error, not an immediate backend player.
- SQLite/WebView: use Spark-owned database/component/ref types rather than raw OP-SQLite/WebView backend types.
- UI: controlled
TextInput.valueis supported;value/defaultValueare exclusive. Select/SegmentedControl share controlled values. Split panes are named, Sidebar selection requires its callback, and glass/symbol components have explicit native limits.
Check feature availability on each target platform. Unknown options reject. Await async cleanup and retain failed handles for retry; a global clear-all operation is not a substitute for ownership.
Configuration and tooling
Use Node 24.19.0+. Run npx --no-install spark ... in apps and bun run spark ... in the source checkout. Runner commands are sdk build-runner, build --runner, and dev --runner-binary. Expo's dev --go selects mobile Expo Go.
Author Spark-owned desktop settings in desktop.config.json, preserve projectId, and compose existing Expo projects through /expo-config, /metro, and /native. Review generated templates/wrappers when updating local consumers. Old Frame native identities/data are not automatically migrated.
See the rename guide for more migration details.