# Upgrading Spark Update Spark, review migrations, and move older prototypes to the current APIs. Source: https://legend.so/spark/migration/ ## [Upgrade an app](https://legend.so/spark/migration/#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. ```sh npx --no-install spark upgrade --dry-run npx --no-install spark upgrade npx --no-install spark doctor ``` The 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](https://legend.so/spark/migration/#move-from-a-preview-to-001) `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: ```sh npm install --save-exact @legendapp/spark@0.0.1 ``` Use 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](https://legend.so/spark/getting-started/#install-just-after-a-release). ### [Changes since next.5](https://legend.so/spark/migration/#changes-since-next5) - 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](https://legend.so/spark/migration/#older-prototypes) Older prototypes need import and contract changes. Removed exports have no aliases. Rebuild matching native runtimes after updating. ## [Import changes](https://legend.so/spark/migration/#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](https://legend.so/spark/migration/#behavior-changes-to-review) - **Windows:** pass explicit IDs; use unified open options/results, display-relative outer-frame geometry, instance-bound listeners/guards, and grouped `macos` chrome. Animate through `setWindowBounds` in `/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 `defaultPath` and 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.value` is supported; `value`/`defaultValue` are 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](https://legend.so/spark/migration/#configuration-and-tooling) Use Node 24.19.0+. Run `npx --no-install spark ...` in apps and `bun run spark ...` in the [source checkout](https://legend.so/spark/getting-started/#contributing-build-spark-from-source). 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](https://github.com/LegendApp/legend-spark/blob/main/docs/legend-spark-migration.md) for more migration details. [View Markdown](https://legend.so/spark/migration.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Upgrading+Spark&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fmigration%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)