Development and runtimes
Use Expo CLI, select Spark Runner or custom binaries, and rebuild native changes.
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
| 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.
npx --no-install spark dev --no-open
npx --no-install spark dev --platform ios
npx --no-install spark dev --port 8082 --localhostExpo 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
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.
npx --no-install spark build --dev --platform macos
# On Windows:
npx --no-install spark build --dev --platform windowsbuild --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:
SPARK_MACOS_ARCH=x64 npx --no-install spark build --dev
SPARK_MACOS_ARCH=x64 npx --no-install spark devSPARK_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
npx --no-install spark analyze
npm run buildAnalysis 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
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:
npx --no-install spark doctor
npx --no-install spark upgrade --dry-run
npx --no-install spark upgradeUpgrade stays on your current release channel and applies versioned migrations. See Upgrading Spark 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, examples and validation, and the SDK development guide.