Runtime Version Policies

## Two layers in every Expo build An app that uses **EAS Update** (the hosted update service) together with the **`expo-updates`** library (the client that runs inside the app) is built as two layers: - **The native layer** is the compiled binary: React Native itself, the Hermes engine, every library that ships Kotlin, Swift or Objective-C code, and native configuration such as permission strings in `Info.plist` and `AndroidManifest.xml`, the app icon and the splash screen. It only changes when a user installs a new build. - **The update layer** is the JavaScript bundle Metro produces plus the images, fonts and other assets that JavaScript loads. This is the part an update replaces. JavaScript reaches the native layer through native modules and native views. If the bundle expects a module, a method or a view that the binary does not contain, it fails at runtime. An update layer is therefore only safe on a binary whose native layer it was written against. ## What `runtimeVersion` is **`runtimeVersion`** is a string that names one particular native layer. You set it in the app config (`app.json` or `app.config.ts`) either as a plain string such as `"1.0.0"` or as a policy object such as `{ "policy": "appVersion" }` that derives the string from something already in the project. Two moments matter: 1. **At build time** the resolved value is written into the binary: the `EXUpdatesRuntimeVersion` key in `Expo.plist` on iOS and the `expo.modules.updates.EXPO_RUNTIME_VERSION` meta-data on Android (with the fingerprint policy, a reserved placeholder plus a bundled hash file). From then on it is fixed for that install, and `Updates.runtimeVersion` from `expo-updates` reads it back at runtime. 2. **At publish time** `eas update` resolves the runtime version again, per platform, from the project as it is at that moment, and stamps that value on the update. The label is only as honest as the project state it is computed from. Nothing compares the two moments for you unless you choose a policy or a CI check that does. ## How EAS decides who receives an update Every update request from the app carries its runtime version (sent as the `Expo-Runtime-Version` header) together with its platform and channel. EAS Update then applies its update policy: - the update's platform must equal the build's platform; - the update's runtime version must equal the build's runtime version **exactly**: no semver range, no "closest compatible" fallback; - the build's channel decides which branch it reads from, which is a separate subject from compatibility. A build therefore only ever sees updates published for its own native layer, and an update stamped with a runtime version that no installed build reports is simply never downloaded. ## What can and cannot go over the air | Change | Ships in an update? | Why | |---|---|---| | Bug fix in a screen, hook or state store | Yes | It lives in the JS bundle | | New image or JSON file loaded by JavaScript | Yes | Assets travel with the update | | Upgrading a pure-JavaScript dependency | Usually | Metro bundles its code, unless it now needs a newer native peer | | Adding, removing or upgrading a library with native code | No | The binary lacks the native half | | Changing a config plugin, permission string, icon or splash | No | These are written into the native projects at build time | | Upgrading the Expo SDK or React Native | No | The whole native layer changes | The rule behind the table is short: **a native change means a new build, and the new build needs a new runtime version.** Only then do you publish updates that rely on the change, targeted at that new runtime. ## When the rule is broken Nothing in EAS inspects the bundle's imports. If a team adds a native library and publishes without changing the runtime version, the update carries the old label, every existing build on that runtime accepts it, and the first import of the new module throws; for an Expo module the error reads `Cannot find native module '...'`. That is why the choice of how the label is computed (by hand or by a policy) matters so much, and why runtime versions are worth logging next to `Updates.updateId` in crash reports. ## Key points - `runtimeVersion` is a compatibility label for native code, not a marketing version, although the `appVersion` policy happens to copy the app version. - Matching is exact and per platform; iOS and Android builds may carry different runtime versions. - An update can change JavaScript and the assets it loads, never native code or native configuration. - Bumping the runtime version is the developer's contract, whether done by hand or delegated to a policy.