How do you upgrade a bare React Native app to a new version, and what does the Upgrade Helper give you?

## Why upgrading is more than one npm install A **bare** React Native app is one where the team owns the `ios/` and `android/` folders. It combines three projects: - a **JavaScript** project (`package.json`, Babel, Metro and Jest config, TypeScript config); - an **iOS** project (`Podfile`, Xcode project, `AppDelegate`); - an **Android** project (Gradle files, `gradle.properties`, `MainApplication`, the Gradle wrapper). Each release of React Native can change the **template** those files were generated from: a new Gradle or Kotlin version, a new `Podfile` helper, a changed app delegate, a new Babel preset. Bumping the npm package alone leaves the native projects on the old template, and the build fails or misbehaves. ## What the Upgrade Helper is The **Upgrade Helper** is a community web tool, linked from the React Native docs and from every release post. You choose the version you are on and the version you want, and it shows the **complete diff of the template** between them, file by file, with inline comments where a change needs explaining. It works for any two versions, but it only shows what changed in the **template**, not what changed in your app's own code or in the libraries you use. ## The procedure 1. **Read the release posts** for every version you cross, especially the **Breaking Changes** and **Deprecations** sections, and the changelog's Breaking and Removed entries. 2. **Update `package.json`** first, as the Helper lists it: `react-native`, the matching `react`, and the `@react-native/*` packages such as the Babel preset, Metro config and TypeScript config. 3. **Apply the other file changes by hand.** For each file the Helper shows, apply the same edit to your version of it. Do not paste the template's file over yours: your `AppDelegate`, `MainApplication`, `Podfile` and `build.gradle` usually carry analytics setup, deep-link handling, flavors or signing that the template does not know about. 4. **Update native libraries** to versions that support the target React Native version. 5. **Reinstall and rebuild**: install JS packages, run `pod install` in `ios/`, clean both native builds, and build iOS and Android. 6. **Test**: unit tests, a smoke pass on both platforms, and the flows most exposed to the release's breaking changes. ## Examples of what the diff contains | Release | Template or config change you would see | |---|---| | 0.85 | Jest config switches to `preset: '@react-native/jest-preset'` | | 0.87 | `compileSdk` and build tools raised to 37 | | 0.87 | recommended AGP 9 opt-outs added to `android/gradle.properties` | The release posts explain the reason for each; the Helper shows the exact lines. ## Hand-merging well - Apply changes in **small commits per file group**, so a broken build points at one area. - When a changed file is heavily customised, re-derive the edit from the comment and the release notes, not from line positions. - Keep a **record of your deliberate deviations** from the template; the next upgrade needs it. - If the build still uses old code after all changes, the docs point first at **caches**: clean the native build folders and restart Metro with its cache cleared before debugging further. ## After the upgrade Commit the lock files (`package-lock.json` or equivalent, `Podfile.lock`) so CI builds the same graph. Watch the first release on the new version closely: runtime behaviour changes, not compile errors, are what escape testing. ## Where upgrades usually go wrong - **Only `react-native` is bumped.** `react` must match the version the release pins (0.87.1 peer-depends on `react` `^19.2.3`), and the `@react-native/*` packages such as `@react-native/babel-preset`, `@react-native/metro-config` and `@react-native/typescript-config` should move with it. - **The diff is pasted, not merged.** A replaced `MainApplication` or `AppDelegate` loses app code and fails in ways that look unrelated to the upgrade. - **Release notes are skipped.** Removals such as `InteractionManager` in 0.87 show up as runtime or type errors in your own code, which no template diff mentions. - **Pods and Gradle caches are stale.** Old build outputs survive the change and make the app appear not to have upgraded at all. - **Only one platform is tested.** A change can compile on iOS and fail on Android, or the reverse, because each platform's template changes independently.