/upgrades

Upgrades Skill

Applicability

• Platforms: iOS and Android
• React Native: 0.76+ (New Architecture interop assumed unless a checklist item says otherwise)

When to Use

• Bumping React Native, React, or the native toolchain
• Turning the New Architecture on, or adding a native module to an app that already uses it
• A native dependency release forces an app upgrade

Severity

• Merge-blocking: the app does not boot on iOS or Android, or a native module stays on a version that does not match this React Native bump.
• Should-fix: how the bump is split, and smoke-test notes.

Guidance

Version jump

• The target version's changelog is read for breaking changes before the bump
• A jump across several minors is split so each step boots, instead of one unreviewed leap
• JS dependencies that ship native code are upgraded in the same change as the React Native bump
• Both iOS and Android build and launch on the new version before the change is merged

Incorrect:

react-native 0.72 → 0.78 in one pull request, Android left for a follow-up

Correct:

One minor at a time, each step building and launching on iOS and Android, with native modules upgraded in the same step

Native version matrix

• Kotlin, the iOS deployment target, and the Android min SDK match what the target React Native version requires
• Codegen has been run for native modules that need it, and the app still builds
• Libraries that ship native code and must move together are upgraded in the same change (navigation screens, gesture handler, and animated-on-the-UI-thread libraries)

Incorrect:

react-native bumped; react-native-screens and react-native-gesture-handler left on the previous major

Correct:

react-native, screens, and gesture-handler moved to the versions that release says belong together, then both platforms launched

New Architecture

• New native modules use the New Architecture interop; a new bridge module is not added without a written reason
• Modules that do not support the New Architecture are listed, and the feature is hidden or replaced until they do
• The app is exercised on a New Architecture build for any screen that touches a native module changed in the upgrade

After the bump

• A smoke pass covers launch, sign-in, and the critical path this app cannot ship without
• Release build settings still point at the right environment (see release-and-updates)
• Source maps or debug symbols still upload so crashes from the new version can be read (see observability)

Anti-Patterns

Pitfalls

• A JS-only bump can still break when a dependency's native pod or gradle version moved.
• Hermes and the JS engine flags change between versions; a crash that exists only in release is easy to miss on a debug smoke test.