# Getting started

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

Source: https://legend.so/spark/getting-started/

Legend Spark: Experimental — not for production.

These guides cover source SDK APIs; the published preview can differ. [Check release status.](https://legend.so/spark/limitations/)

Experimental

Spark is experimental and not ready for production use. See [status and limitations](https://legend.so/spark/limitations/).

## [Prerequisites](https://legend.so/spark/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](https://legend.so/spark/getting-started/#create-an-app)

Create an app with npm:

```sh
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:

```sh
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:

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

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

```sh
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](https://legend.so/spark/getting-started/#run-and-edit)

From the generated app:

```sh
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](https://legend.so/spark/development/#native-changes).

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](https://legend.so/spark/getting-started/#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:

```sh
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](https://legend.so/spark/distribution/) for signing setup and distribution.

## [Contributing: build Spark from source](https://legend.so/spark/getting-started/#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:

```sh
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](https://github.com/LegendApp/legend-spark/blob/main/docs/windows-slice.md). 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](https://legend.so/spark/development/#sdk-iteration-and-diagnostics) for refreshing local apps after source changes.

[View Markdown](https://legend.so/spark/getting-started.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Getting+started&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fgetting-started%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)