The native binary is an API contract

Part 8 · Best practices

The native binary is an API contract

Prerequisites: 05-expo-module-contract

Build-time native surface and update-time JS surface. An OTA update cannot add a new compiled native module. Nodes: App config, Prebuild / compile, Installed binary, OTA update, runtimeVersion. — Build-time native surface and update-time JS surface. An OTA update cannot add a new compiled native module. [S08] [S09]

Mental model verified

Expo Go contains a fixed native library set. A development build includes your chosen native packages. CNG generates Android and iOS projects from config; config plugins describe persistent changes to native project files. A runtimeVersion links OTA updates to compatible binaries.

[S08] [S09]

Worked example synthesis

Adding a native payment SDK changes the binary. Install it, configure its plugin, create and test new Android/iOS development and production builds, then publish JS updates only to the matching runtime.

[S08] [S09]

Engineering choice verified

Treat every native dependency/config change as a release compatibility event. Use a runtimeVersion policy and test a preview build with the same native runtime before rollout.

[S09]

Pitfall and next step verified

Editing generated AndroidManifest.xml or Info.plist directly in a CNG workflow can be lost on prebuild. Encode changes in config plugins and check generated projects on both platforms.

[S08]

Keep this: A JS update can only use native APIs already compiled into a compatible binary.

Check yourself: Why does adding a native package require a new app build?

Its native implementation is absent from binaries already installed; an OTA JS update cannot compile that code into them.