# 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/

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

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

### [Choose a release](https://legend.so/spark/getting-started/#choose-a-release)

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

Move into the app and start it:

```sh
cd MyApp
```

```bash
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](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:

```bash
npm run build
```

```sh
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 --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](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)