<!-- Stacklift documentation: "OTA for every stack". Source: https://stacklift.joynul.com/docs/ota-layers · All pages for LLMs: https://stacklift.joynul.com/llms-full.txt -->

> About Stacklift: Stacklift is a hosted platform with source-available SDKs for shipping app releases and over-the-air updates. It works for mobile (React Native, Expo, Flutter, native iOS and Android, Kotlin Multiplatform, .NET MAUI, Unity), web, desktop (Electron, .NET, Java) and backend apps. Developers create releases with the `stacklift` CLI or the dashboard; the server verifies and signs every artifact (SHA-256 + Ed25519), deploys releases to channels with staged rollouts and rollback, and app SDKs check, download and verify updates. Native apps can change screens over the air with server-driven UI layouts and logic with sandboxed scripts, within App Store and Google Play rules. Apps never depend on Stacklift to keep working: everything has a built-in fallback and an exit path.
>
> This page: What can be updated over the air for each stack, and how: config, layouts, scripts, code push.

# Over-the-air updates for every mobile stack

Stacklift can update most of an app without a store release, but not by replacing compiled code. Apple and Google both forbid that for native apps. What they allow is data, and code that runs inside an interpreter the OS provides. Stacklift offers four layers, from safest to most powerful. Use the lowest layer that does the job.

| Layer | What changes | Where it works | Status |
| --- | --- | --- | --- |
| 1. Config, flags, assets | JSON settings, feature flags, images, content packs | Every stack | Built |
| 2. Server-driven UI | Screens described as data: text, order, sections, lists, tables, buttons | SwiftUI, Jetpack Compose, Flutter | Built ([guide](https://stacklift.joynul.com/docs/server-driven-ui.md)); React Native, MAUI and Unity renderers not yet |
| 3. Scripted logic | Signed JavaScript run in the OS interpreter, called from hooks you write | Native iOS and Android, Flutter, KMP, MAUI, Unity | Server, Swift, Android (Kotlin) and Flutter runtimes built; C# runtime not yet |
| 4. Code push | The app's own JavaScript or web code | React Native, Expo, Capacitor, NativeScript | React Native built ([below](#layer-4-code-push-for-react-native)); Expo, Capacitor and NativeScript loaders not yet |
| (Flutter code push) | Compiled Dart code | Flutter | Not built. Needs a patched Flutter engine |

## Why compiled code cannot be pushed

- **iOS:** the Apple Developer Program License Agreement (3.3.2) only allows downloaded *interpreted* code, and only if it does not change the app's primary purpose, does not create a store for other code, and does not bypass signing or the sandbox.
- **Android:** Google Play's Device and Network Abuse policy forbids downloading executable code (dex, JAR, `.so`) from outside Play, except code that runs in a virtual machine or interpreter with only indirect access to Android APIs.

Any tool that claims to replace compiled Swift, Kotlin, C# or Dart on a store build is outside those rules, or relies on a patched runtime such as Shorebird's Flutter engine. Stacklift does not do that for native apps.

## Layer 3: scripted logic

You write the parts of your app that change often (pricing rules, ranking, validation, feature logic) as small JavaScript functions, and the app calls them through hooks. The script ships through Stacklift like any release: signed, checksummed, rolled out in stages, and rolled back from the dashboard if needed.

What the script can do is what the interpreter and your registered functions allow. It has no network, files, timers, modules or native objects. Everything it can reach, you registered explicitly.

### Release it

```bash
stacklift release create --version 1.4.1 --runtime-version 1 \
  --artifact ios:script-bundle:./rules.js --channel production --deploy
```

A `script-bundle` is a single `.js` file up to 2 MB for `ios` or `android`. Updates only reach apps with the same `--runtime-version`, so bump it when the hooks your app exposes change.

### Use it from Swift

A runnable SwiftUI example with a walkthrough is in [`examples/swift-scripts`](https://github.com/Joynul-Abedin/stacklift/tree/main/examples/swift-scripts).

```swift
import Stacklift

let client = StackliftClient(StackliftOptions(baseURL: deliveryURL, apiKey: publicKey, pinnedPublicKey: pinnedPEM))
let scripts = StackliftScripts(client: client, options: .init(runtimeVersion: "1", currentVersion: appVersion))

scripts.register("flag") { json in  /* the only functions the script can call: host.flag(...) */ "true" }

// 1. Early in launch: apply a staged script, or roll back one that never confirmed.
scripts.prepareLaunch()

// 2. Where the app needs the logic. Returns nil when no script is active, so your built-in code is the fallback.
let discount: Double = (try? scripts.call("rules.discount", cart)) ?? defaultDiscount(cart)

// 3. Once the app is healthy (for example after the first screen appears).
scripts.confirmLaunch()

// 4. In the background: check, download, verify and stage. It takes effect on the NEXT launch.
Task { _ = try? await scripts.stage(); await scripts.flushEvents() }
```

How it behaves:

- **Apply on next launch.** A downloaded script is never swapped in mid-session.
- **Verified first.** The Ed25519 signature is checked before anything is downloaded, then the size and SHA-256 of the bytes. Pin the project's public key in the app; without it a compromised server could vouch for its own script.
- **Syntax-checked before staging.** A script that does not parse is refused and never retried.
- **Automatic rollback.** If a launch never reaches `confirmLaunch()` twice in a row (a crash, a hang), the script is discarded and the last confirmed one, or your built-in behaviour, takes over. A script that throws while loading is discarded immediately. A discarded release is never staged again on that device.
- **Reported.** Downloads, successful installs and rollbacks are sent to Stacklift, so the dashboard shows adoption and failure rates and can pause a bad rollout.

### Use it from Android (Kotlin)

`packages/sdk-android` runs scripts in QuickJS (Android has no interpreter built in) with the same lifecycle and the same `host` bridge:

```kotlin
val scripts = StackliftScripts(client, StackliftAndroid.options(context, "scripts", runtimeVersion = "1"))
scripts.register("appName") { "\"My App\"" }            // scripts call host.appName(); JSON in, JSON out
scripts.prepareLaunch()                                   // early in launch
val discount = scripts.call("rules.discount", mapOf("total" to cart.total)) as? Number ?: builtInDiscount(cart)
scripts.confirmLaunch()                                   // once healthy
lifecycleScope.launch { scripts.stage(); scripts.flushEvents() }
```

Memory is capped (32 MB) and every call has a time limit (2 s); a script that hangs is abandoned and rolled back. There is no `setTimeout`, `fetch`, `require` or file access, which tests on the emulator check.

### Use it from Flutter

Two packages: `stacklift` (`packages/sdk-dart`, the state machine and verification, no interpreter) and `stacklift_scripts_flutter` (`packages/sdk-flutter-scripts`, the interpreter: JavaScriptCore on iOS and macOS, QuickJS on Android, Windows and Linux, through `flutter_js`). Neither is published yet; add them as path or git dependencies.

Android builds: `flutter_js` compiles Kotlin for JVM 1.8 and Java for 11, which Android Gradle Plugin 9 refuses by default. Add `kotlin.jvm.target.validation.mode=warning` to `android/gradle.properties` until the plugin is updated (the code runs fine; verified on an Android 17 emulator).

```dart
import 'package:stacklift/stacklift_io.dart';
import 'package:stacklift_scripts_flutter/stacklift_scripts_flutter.dart';

final scripts = StackliftScripts(
  client: StackliftClient(baseUrl: deliveryUri, apiKey: publicKey, pinnedPublicKey: pinnedPem),
  engine: const FlutterJsEngine(),
  directory: Directory('${(await getApplicationSupportDirectory()).path}/stacklift-scripts'), // path_provider
  runtimeVersion: '1',
  deviceId: await DeviceId.getOrCreate(myKeyValueStore),
  platform: currentStackliftPlatform(),
  currentVersion: appVersion,
);

scripts.register('flag', (json) => 'true');            // the only functions a script can call: host.flag(...)
scripts.prepareLaunch();                                // early in main(): apply a staged script or roll one back
final discount = scripts.call<num>('rules.discount', cart) ?? defaultDiscount(cart);   // null: use your built-in Dart code
WidgetsBinding.instance.addPostFrameCallback((_) => scripts.confirmLaunch());           // the first frame drew: this launch is healthy
unawaited(scripts.stage().then((_) => scripts.flushEvents()));                          // background: stage for the next launch
```

A runnable example with a walkthrough is in [`examples/flutter-scripts`](https://github.com/Joynul-Abedin/stacklift/tree/main/examples/flutter-scripts). Behaviour is identical to the Swift runtime: verified before anything is downloaded, syntax-checked, applied only on the next launch, rolled back after two launches that never confirm, and reported to the dashboard. Calls are synchronous, so scripts must be synchronous too: promises and timers are not available (`setTimeout` and friends are removed from the sandbox).

What the Flutter adapter removes from the interpreter, because a script must not reach it: `setTimeout`, `setInterval`, `fetch`, `XMLHttpRequest`, `require`, `process`, `WebAssembly`, the raw `sendMessage` bridge and the package's internal helpers. A test runs a real interpreter and checks each one is `undefined`.

### Rules for staying within the stores' policies

You are responsible for compliance. In practice:

- Scripts may change *how a feature you already shipped behaves*, not add features or change the app's purpose.
- Do not register a host function that gives a script raw platform access (reflection, file system, arbitrary network, running other code).
- Do not use scripts to build a store or runtime for third-party code.
- Describe it truthfully in your App Review notes if asked.

### Limits you should know about

- **Hooks first.** Only logic that sits behind a hook can change. Everything else needs a store release.
- **No time limit on iOS.** JavaScriptCore cannot interrupt a script that loops forever, so keep scripts small and call them off the main thread. A hang counts as an unconfirmed launch and rolls back, but the user still sees the hang once. On Android each call has a time limit (2 s by default): a script that exceeds it is abandoned and rolled back at once.
- **Swift, Android and Flutter.** The runtime exists for Swift (`packages/sdk-swift`), native Android (`packages/sdk-android`: 14 JVM tests plus 9 tests with real QuickJS on an emulator) and Flutter (`packages/sdk-dart`, plus 14 tests with the real interpreter in `packages/sdk-flutter-scripts`). The C# runtime (MAUI, Unity) is not built; the server side and signing already work for it.
- **Tested in real apps on simulators, an emulator and one physical Android phone.** On a physical HONOR ELI-NX9 (Android 16), `examples/android-scripts` downloaded a script and a layout, applied them on the next launch and rolled back a script that never confirmed, and the 15 SDK device tests (real QuickJS and Compose) pass. On a Pixel 6 Pro emulator (Android 17), `examples/android-scripts` (Compose) and `examples/flutter-scripts` downloaded a script and a layout from one release and applied them on the next launch, and the native app rolled back a script that never confirmed after two launches (the server counted 1 download and 1 failure). On iOS: `examples/flutter-scripts` (Flutter) and `examples/swift-scripts` (SwiftUI, Swift 6) each ran as a debug build on the iOS simulator against a live Stacklift server: download, apply on next launch, upgrade, automatic rollback after two unconfirmed launches, and a bad release never re-staged. The Swift app also checked its saved state at every launch (active, pending, last good, bad releases) and the server's counts (3 downloads, 2 installs, 1 failure). A physical iPhone and release builds have not been run.
- **Script syntax check.** Flutter checks syntax by parsing the script as a function body (so nothing runs). A script that is only valid as a top-level script, for example one with a top-level `return`, would parse differently; it fails at load and is discarded.

## Layer 4: code push for React Native

React Native apps run JavaScript, so the whole app's JavaScript can change over the air, not only logic behind hooks. `@stacklift/react-native` (`packages/sdk-react-native`) does it with the same launch-safe rules as scripts and layouts:

1. A `js-bundle` release (a zip with the bundle at the top and its assets next to it) is downloaded and verified in the background, then unpacked into its own folder.
2. On the **next launch**, the native side hands React Native the new bundle instead of the one built into the app: `bundleURL()` on iOS, `jsBundleFilePath` on Android. Nothing changes mid-session.
3. JavaScript calls `Stacklift.confirmLaunch()` once the first screen is up. That bundle becomes the last good one.
4. If something fails before that, the bundle is discarded, never downloaded again, and the app restarts straight into the last good bundle:
   - `StackliftErrorBoundary` catches errors while rendering (React Native does not pass those to its global error handler).
   - `Stacklift.installCrashGuard()` catches other fatal JavaScript errors.
   - The decision is saved synchronously, before anything else can go wrong.
   - The restart reloads JavaScript on iOS and starts a new process on Android (where the bundle file is fixed when React Native starts). It waits until React has finished its current work, because reloading mid-commit crashes React Native's renderer.
   - If even that fails (a native crash, or the app killed), two launches that never confirm roll back automatically.

```bash
npx react-native bundle --platform ios --dev false --entry-file index.js --bundle-output dist/ios/main.jsbundle --assets-dest dist/ios
(cd dist/ios && zip -qr ../ios.zip .)
stacklift release create --version 1.0.1 --runtime-version 1 --artifact ios:js-bundle:dist/ios.zip --channel production
```

See the [package README](https://github.com/Joynul-Abedin/stacklift/tree/main/packages/sdk-react-native) for setup: two native lines, Info.plist or AndroidManifest keys, and the Podfile line.

**Verified on the iOS simulator and an Android 17 emulator** (`examples/react-native-demo`, React Native 0.88.1 with the new architecture and Hermes, release builds, against a live server):
- A release carrying a new bundle and a new layout was downloaded, and the next launch ran the new JavaScript and drew the new screen, on both platforms.
- A bundle that crashed while rendering was discarded on its first failure, and the app restarted itself on the last good bundle without crashing, on both platforms. That release is never downloaded again.
- Without the error boundary, the two-unconfirmed-launches rule rolled a crashing bundle back on its own (after two crashes).
- The server counted every outcome: each good release installed, each crashing release 1 download and 1 failure.
- With code shrinking (R8) on, on the Android emulator: the same update and the same crash recovery worked, and so did scripts in the native Android demo (a script that throws on load was rolled back). No keep rules beyond the SDK's own were needed. Shrunk builds have not been run on a phone.
- On a physical HONOR ELI-NX9 phone (Android 16), the same release build was updated over the air (including a fix for a dark-mode bug that only showed on the phone, shipped as a code push update), recovered from a crashing bundle by restarting itself, and the server counted each outcome. A physical iPhone has not been run.

**Store rules:** both stores allow this for interpreted JavaScript that does not change the app's purpose. Native code, native modules, permissions and React Native upgrades still need a store release and a new runtime version.

## What to build next

1. A C# runtime and renderer for MAUI and Unity. (The Kotlin runtime and Compose renderer for Android are built.)
2. Layer 4 loaders for Expo and Capacitor (React Native is built). Expo's update protocol is open, so Stacklift can act as an Expo update server with no custom client.
3. Eject to Compose and React Native code (`ui export` writes SwiftUI or Flutter today).
4. Flutter code push, only if Shorebird agrees in writing or Stacklift builds its own engine.
