#Sparkling CLI

Sparkling CLI (sparkling-app-cli) is the built-in command-line tool that powers the development workflow. It handles building Lynx bundles, autolinking native method modules, running apps on Android/iOS, and diagnosing your environment.

#Installation

The CLI is included automatically when you scaffold a project with create-sparkling-app. You can also install it manually:

npm install sparkling-app-cli

Once installed, run commands via npx sparkling or through the npm scripts defined in your project's package.json.

#Commands

#sparkling build

Build Lynx bundles using your project's app.config.ts.

npx sparkling build

By default, asset copying is skipped for faster iteration during development. Use --copy when you need the bundles inside the native projects (e.g. for a release build).

#sparkling dev

Start the Rspeedy dev server for hot-reload development. Instead of rebuilding and copying bundles manually, the dev server serves bundles over HTTP so changes are reflected instantly.

npx sparkling dev

The default port 5969 spells LYNX on a phone keypad (L=5, Y=9, N=6, X=9).

Port resolution priority is:

1. --port
2. app.config.ts dev.server.port
3. app.config.ts lynxConfig.server.port
4. 5969

If you run sparkling dev --port <number>, the CLI writes it back to app.config.ts as dev.server.port.

Once the server is running, point your app to http://<your-ip>:5969/main.lynx.bundle (or whatever entry point you need). In the project template, DEBUG builds connect to the dev server automatically.

#sparkling copy-assets

Copy compiled bundles into Android and iOS resource directories.

npx sparkling copy-assets

#sparkling autolink

Discover Sparkling method modules for Android and iOS. The CLI scans for module.config.json files in the workspace and node_modules, then updates the native Sparkling method links and generates Sparkling registry files. Host apps also enable the Lynx library Autolink plugins, so non-method Lynx libraries that ship lynx.lib.json can be linked by the Lynx toolchain.

npx sparkling autolink

What it does:

• Android — Links Sparkling method Gradle projects and generates SparklingAutolink.kt. Debug-tool packages are linked as debugImplementation.
• iOS — Links Sparkling method pods and generates SparklingAutolink.swift. Debug-tool packages are linked in the debug target.

#sparkling run:android

Build, autolink, and launch the Android debug build in one step.

npx sparkling run:android

This command will:

1. Autolink method modules for Android
2. Resolve the dev port from app.config.ts and auto-start a dev server if needed
3. Auto-detect device type and inject host for template debug URL:
   • emulator: 127.0.0.1 (and auto adb reverse)
   • physical device: host LAN IPv4
4. Build the Lynx bundle
5. Run gradlew assembleDebug
6. Install the APK on a connected device/emulator
7. Launch the main activity

#sparkling run:ios

Build, autolink, and launch the iOS simulator build in one step.

npx sparkling run:ios

This command will:

1. Pick a simulator (prefers a booted device; falls back to common names like iPhone 17 Pro)
2. Resolve the dev port from app.config.ts and auto-start a dev server if needed
3. Autolink method modules for iOS
4. Run pod install (unless --skip-pod-install)
5. Build the Lynx bundle
6. Build, install, and launch the app on the simulator

You can also set the SPARKLING_IOS_SIMULATOR environment variable to specify a default simulator.

#sparkling doctor

Verify that your development environment is properly set up.

npx sparkling doctor

The doctor command checks:

If any check fails, the output includes a hint on how to fix it.

#Global Options

All commands support the following flag:

You can also set the SPARKLING_VERBOSE environment variable for the same effect.

#Typical Workflow

# 1. Create a project
npm create sparkling-app@latest my-app
cd my-app

# 2. Check your environment
npx sparkling doctor

# 3. Start the dev server for hot-reload development
npx sparkling dev

# 4. Run on Android
npx sparkling run:android

# 5. Run on iOS
npx sparkling run:ios

# 6. Build bundles for release
npx sparkling build --copy