Getting started

Create a macOS app from npm, edit it with Fast Refresh, and build a standalone app.

Prerequisites

Use macOS 14 or newer on Apple Silicon with Node 24.19.0 or newer.

Creating an app and running it with Spark Runner does not require Xcode or CocoaPods. You need those tools when compiling a standalone app or a custom native development build.

Create an app

npm create @legendapp/spark@next MyApp

The creator installs the app's dependencies, including the spark CLI. Commit the generated lockfile and spark-packages/ archives so other machines can reinstall the same dependencies.

The creator uses its own bundled Spark release by default. Pass --latest for the current stable release or --spark-version <version|tag> for a specific release. If the selected release differs from the creator's version, it prints the exact matching creator command to run.

Run and edit

Move into the app and start it:

cd MyApp

npm run macos

The first launch downloads and verifies the matching macOS ARM64 Spark Runner. Later sessions reuse it. Expo CLI starts Metro and opens your app.

Open App.tsx, change the Hello, Legend Spark text, and save. JavaScript changes appear through Fast Refresh. Extra native dependencies or native configuration can require a custom development build.

The generated app includes these scripts:

Command	Purpose
`npm run macos`, `npm run dev`, `npm start`	Start the development session
`npm run build`	Compile a standalone macOS app
`npm run package`	Sign and notarize a distribution archive
`npm run doctor`	Check native build prerequisites and dependency pins

Build a standalone app

Install full Xcode, complete its first-launch setup, and select it in the Xcode command-line tools settings. Install CocoaPods and ensure pod is on your PATH. Command Line Tools alone cannot compile the app.

Stop the development session with Ctrl+C, then run:

npm run build

npx --no-install spark open

The build prints the location of an ad-hoc-signed .app with embedded JavaScript. It runs without Metro. spark open launches the last standalone build.

To prepare a signed, notarized archive with your Developer ID credentials, use npm run package. See packaging and updates for signing setup and distribution.

Contributing: build Spark from source

For framework development, install Git and the checkout's pinned Bun 1.3.14, in addition to Node and the native build tools above:

git clone https://github.com/LegendApp/legend-spark.git
cd legend-spark
bun install --frozen-lockfile
bun run spark sdk pack
bun run spark sdk build-runner
bun run spark create /absolute/path/to/MyApp
cd /absolute/path/to/MyApp
npm run macos

sdk pack creates local SDK archives and registers their manifest. sdk build-runner compiles and registers a matching Runner. To reuse an existing matching Runner, run bun run spark sdk register /absolute/path/to/SparkRunner.app from the checkout instead of building it. Keep the registered Runner app at that path.

For Windows 11 source development, follow the Windows guide. Use --platform windows with sdk pack, sdk build-runner, and create, then run the generated windows script. Windows native compilation and runtime behavior still need validation; production distribution is unsupported.

See SDK iteration for refreshing local apps after source changes.