Getting started

Prerequisites

Use macOS 14 or newer on Apple Silicon with Node 24.19.0 or newer. npm comes with Node; pnpm, Yarn, and Bun are also supported package managers. Bun is optional for app development.

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

Create an app with npm:

npm create @legendapp/spark@next MyApp
cd MyApp

The command runs @legendapp/create-spark, which creates the app and installs its dependencies. @legendapp/spark includes the spark CLI and the public APIs.

Other package managers:

bun create @legendapp/spark@next MyApp
pnpm create @legendapp/spark@next MyApp
yarn create @legendapp/spark@next MyApp # Yarn 2+

For Yarn Classic (1.x), use npm to run the tagged creator and select Yarn for installation:

npm create @legendapp/spark@next MyApp -- --package-manager yarn

To choose a package manager, pass --package-manager npm|pnpm|yarn|bun. For example:

npm create @legendapp/spark@next MyApp -- --package-manager pnpm

The chosen manager must be installed. The commands below use npm; use your chosen manager's run command instead if needed. Keep the generated lockfile and spark-packages/ archives in version control so other machines can reinstall the same inputs.

Run and edit

From the generated app:

npm run macos

On the first launch, Spark downloads and verifies the matching macOS ARM64 Spark Runner. This requires an internet connection. Later sessions reuse the downloaded Runner. Expo CLI starts Metro and opens your app in the Runner.

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:

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
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.