# Development and runtimes

Use Expo CLI, select Spark Runner or custom binaries, and rebuild native changes.

Source: https://legend.so/spark/development/

`npm run dev`, `npm start`, and the generated desktop scripts enter one managed Expo CLI development session. Expo owns Metro, logs, reload, debugging, and mobile/web actions; Spark adds desktop runtime selection and compatibility checks.

## [Terminal actions](https://legend.so/spark/development/#terminal-actions)

| Key | Action |
| --- | --- |
| `d` | Open the host desktop target |
| `g` | Switch Spark Runner/custom development build without compiling |
| `b` | Build and open a required custom development binary |
| `r`, `j`, `m` | Expo reload, debugger, and development menu |
| `i`, `a`, `w` | Declared iOS, Android, and web targets |
| `s` | Mobile Expo Go/development-client selection |
| `?` | Current command table |
| Ctrl+C | Exit the session and close its owned native app |

Expo Go is a mobile runtime; it is separate from Spark Runner. Switching binaries or restarting Metro can reset React state. Desktop selection is remembered in `.spark/settings.json`.

A universal session serves all declared targets. A missing/incompatible desktop binary blocks that desktop bundle while mobile/web remain available. `--platform` chooses an initial launch; it does not add a platform to the project.

```sh
npx --no-install spark dev --no-open
npx --no-install spark dev --platform ios
npx --no-install spark dev --port 8082 --localhost
```

Expo start flags such as `--clear`, `--offline`, `--lan`, `--tunnel`, and `--max-workers` pass through. Use `spark dev --help` for the full list. Desktop launch uses the port Expo reports.

## [Native changes](https://legend.so/spark/development/#native-changes)

Extra native modules, URL/document associations, helper binaries, or native settings/plugins can require an app-specific build. Spark checks native requirements before loading JavaScript; it does not automatically compile every edit.

```sh
npx --no-install spark build --dev --platform macos
# On Windows:
npx --no-install spark build --dev --platform windows
```

`build --dev --force` forces regeneration and compilation. Author durable native changes in packages/config plugins; generated native directories are disposable. Run native generation/build operations sequentially in one checkout.

To select Intel macOS from a consumer project:

```sh
SPARK_MACOS_ARCH=x64 npx --no-install spark build --dev
SPARK_MACOS_ARCH=x64 npx --no-install spark dev
```

`SPARK_MACOS_ARCH=arm64|x64` and `SPARK_WINDOWS_ARCH=x64|arm64` select build targets. The matching architecture is part of runtime compatibility. Intel macOS and Windows native builds and runtime behavior still need validation. No hosted Windows Runner exists; build one locally.

## [Production selection](https://legend.so/spark/development/#production-selection)

```sh
npx --no-install spark analyze
npm run build
```

Analysis records production reachability in `.spark/selection-report.json`. SDK native modules can be pruned; unknown third-party native dependencies are retained. Keep native-only requirements in configuration. `build --preview` uses the production native selection in Debug; it is distinct from the standalone embedded-bundle build.

## [SDK iteration and diagnostics](https://legend.so/spark/development/#sdk-iteration-and-diagnostics)

After SDK source changes, run `node scripts/refresh-consumer.ts /path/to/app` from the framework checkout to refresh a test app. Rebuild/register its Runner when the native signature changes.

Use `spark doctor` to check native prerequisites and dependency pins. Preview upgrades before applying them:

```sh
npx --no-install spark doctor
npx --no-install spark upgrade --dry-run
npx --no-install spark upgrade
```

Upgrade stays on your current release channel and applies versioned migrations. See [Upgrading Spark](https://legend.so/spark/migration/) to move from a preview to 0.0.1. Keep React and Expo on Spark's tested pins. Doctor also reports outdated Enriched HTML web dependencies; upgrade repairs their pins.

Build logs and diagnostic reports live under `.spark/`. Keep generated diagnostics out of version control.

See [configuration](https://legend.so/spark/configuration/), [examples and validation](https://legend.so/spark/examples/), and the [SDK development guide](https://github.com/LegendApp/legend-spark/blob/main/docs/development.md).

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