Sanniv Khare 8 min read

React Native 0.88 upgrade order, built and timed step by step

React Native 0.88: the dependency order npm forces first

The safe way to reach React Native 0.88.1 is four steps, each one building on its own: react-native-worklets 0.13 and Reanimated 4.7 together, then Gesture Handler 3, then react-native-screens and safe-area-context, and only then React Native itself, with every @react-native/* package and a fresh lockfile in the same change. We ran that chain on a fresh React Native 0.87.1 app on our M1 lab Mac (macOS 15.7.3, Xcode 26.2, iOS 26.3 Simulator, Node 24.22.3, npm 11.19.1, CocoaPods 1.17.0, JDK 17) on 15 November 2026, with a clean iOS Release build after every step and Android release builds at both ends. Three things surprised us: npm only warns when worklets moves without Reanimated, it refuses the React Native bump while the 0.87 lockfile is still there, and pod install kept the 0.87.1 prebuilt iOS core until we ran pod update React-Core-prebuilt.

Why we did this: our React Native CLI banking app uses the same five libraries, and we wanted the order proven on a throwaway app before it touches real code.

The test app

A fresh @react-native-community/cli init app on React Native 0.87.1 with one screen that actually uses the stack: a card you drag with Gesture.Pan() inside GestureDetector, animated with a Reanimated shared value, inside GestureHandlerRootView, SafeAreaProvider and enableScreens(). The Babel config has the react-native-worklets/plugin. The screen uses only the Gesture Handler API that exists in both 2.x and 3.x, so the same file had to build at every step.

Starting set: react-native 0.87.1, react 19.2.3, react-native-worklets 0.12.2, react-native-reanimated 4.6.0, react-native-gesture-handler 2.33.1, react-native-screens 4.29.0, react-native-safe-area-context 5.10.1.

The test app on React Native 0.87.1 and on 0.88.1 in the iOS 26.3 Simulator

The drag card at the start and after the last step: Release builds on an iPhone 17 Pro Simulator, iOS 26.3.

The order, and what each step cost

The upgrade order that built at every step

Each step: change the versions, pod install, delete derived data, then a clean xcodebuild Release build for the Simulator. App size is the .app bundle; the JS bundle is the main.jsbundle inside it.

Step What changed pod install Clean iOS Release build .app main.jsbundle
Start RN 0.87.1 set above 35 s 5m 54s (first build) 51.3 MB 2.34 MB
A worklets 0.13.1 + Reanimated 4.7.1 16 s 3m 48s 52.1 MB 2.45 MB
B Gesture Handler 3.5.0 16 s 4m 22s 52.8 MB 2.55 MB
C screens 4.30.1 + safe-area-context 5.11.1 17 s 4m 13s 52.9 MB 2.55 MB
D React Native 0.88.1 + react 19.3.0 2m 56s, then pod update 1m 52s 3m 49s 55.3 MB 2.54 MB

The first clean build was the first one on a freshly set-up Mac and ran 1.5 to 2 minutes longer than the next three; read the A to C builds against each other, not against it. These are single runs on one Mac, useful for “did anything blow up”, not as benchmarks. On Android, a release build of the arm64-v8a ABI took 12 min 40 s at the start (APK 26.1 MB) and 3 min 56 s on 0.88.1 (APK 27.3 MB). That first Android build also downloaded Gradle 9.4.1 and every dependency, so compare the two APK sizes, not the two times. Neither Android build needed a code or Gradle change: the Android template is identical between 0.87.1 and 0.88.1.

Step D’s pod install was the slow one because 0.88.1 ships new Hermes and React Native core binaries for iOS that had to be downloaded. The .app grew about 2.4 MB on 0.88.1 while the JS bundle barely changed, so the growth is on the native side.

Step A: worklets and Reanimated move together

Reanimated 4.6.0 requires worklets 0.12.x; Reanimated 4.7.x requires worklets 0.13.x. Both 4.7 and worklets 0.13 accept React Native 0.86 to 0.88 in their peer ranges, so this step can land while you are still on 0.87.

What we did not expect is how quietly npm handles getting it wrong. Moving worklets alone, with Reanimated 4.6.0 still installed:

npm 11 warns about the worklets peer range but still installs

npm 11.19.1 prints an ERESOLVE overriding peer dependency warning and installs worklets 0.13.1 anyway.

That is a warning, not an error, so in CI it scrolls past. The mismatch then shows up later in the native build or at runtime, far from the change that caused it. Install the pair in one command:

npm install --save-exact react-native-worklets@0.13.1 react-native-reanimated@4.7.1
cd ios && pod install

With both in one install, npm resolved cleanly (“changed 2 packages in 15s”) and the iOS build passed.

Step B: Gesture Handler 3 kept our screen building

Gesture Handler 3 is a major release, but the code path most apps use survived: the 3.5.0 GestureDetector accepts the builder-style Gesture.Pan() objects and hands them to its legacy detector. Our screen built on 3.5.0 with no code change, and it rendered in the final 0.88.1 run shown below.

What did change is the export list. We diffed the public index.ts of 2.33.1 and 3.5.0 from the npm packages:

  • Gone: Swipeable, DrawerLayout, gestureHandlerRootHOC, enableExperimentalWebImplementation, enableLegacyWebImplementation.
  • Renamed: createNativeWrapper is now legacy_createNativeWrapper; the old RectButton, BaseButton, BorderlessButton, Pressable, ScrollView, FlatList, Switch, TextInput and RefreshControl live on as Legacy* exports.
  • New: hook-based gestures such as usePanGesture, useTapGesture and useSimultaneousGestures, plus new component implementations under the old button and list names.

So grep your app for the removed names before this step. If none appear, the step is a version bump.

Step C: screens and safe-area-context

Both declare react-native: "*" as their peer, so npm never forces their timing. They moved in one install with no warnings and the build passed. We did them before React Native only to keep the 0.88 step small.

Step D: React Native 0.88.1, and the lockfile

React Native 0.88.1 needs react 19.3.0, and @react-native/new-app-screen 0.87.1 pins react-native to exactly 0.87.1, so the runtime and every @react-native/* package have to move in the same change. We set all of them in package.json first, the way Upgrade Helper lays it out:

npm pkg set dependencies.react-native=0.88.1 dependencies.react=19.3.0 \
  dependencies.@react-native/new-app-screen=0.88.1 \
  devDependencies.@react-native/babel-preset=0.88.1 \
  devDependencies.@react-native/eslint-config=0.88.1 \
  devDependencies.@react-native/jest-preset=0.88.1 \
  devDependencies.@react-native/metro-config=0.88.1 \
  devDependencies.@react-native/typescript-config=0.88.1 \
  devDependencies.react-test-renderer=19.3.0

Then npm install failed anyway:

With the 0.87.1 lockfile in place, npm refuses the 0.88.1 versions

Every version in package.json said 0.88.1; the lockfile still held the 0.87.1 tree, and npm would not move it.

Deleting node_modules and package-lock.json and installing again resolved the whole 0.88.1 set in 85 seconds. We checked the same package.json with npm 10.9 and saw the same result: it refuses with the old lockfile and resolves with a fresh one. Commit the new lockfile in the same PR so reviewers see the full tree change.

Step D, part two: pod install keeps the old prebuilt core

With the packages on 0.88.1 and the scene changes applied, the first 0.88 build failed:

After pod install the iOS build failed because React-Core-prebuilt was still 0.87.1

The 0.88.1 headers do declare these APIs; the build was compiling against the 0.87.1 prebuilt core that Podfile.lock still pinned.

React Native’s iOS core comes as a prebuilt pod, React-Core-prebuilt. After the bump, Podfile.lock listed React at 0.88.1 but React-Core-prebuilt still at 0.87.1, and a plain pod install keeps whatever the lockfile pins. The new SceneDelegate calls startReactNative(withModuleName:in:connectionOptions:) and RCTLinkingManager.scene(...), which exist only in the 0.88 core, so the Swift compiler stopped there.

pod update React-Core-prebuilt moved it to 0.88.1, and the same build then passed in 3 min 49 s. Check the lockfile after every React Native bump:

cd ios && pod install
grep -E "^  - React-Core-prebuilt|^  - React \(" Podfile.lock   # both should show the new version
pod update React-Core-prebuilt                                  # if they don't

The iOS template change in 0.88: scenes

Apart from the version numbers in package.json, the only changes between @react-native-community/template 0.87.1 and 0.88.1 are on iOS. The Android template is identical. App startup moves from AppDelegate into a new SceneDelegate:

AppDelegate.swift in the 0.87.1 template next to SceneDelegate.swift in the 0.88.1 template

In 0.88.1 the AppDelegate becomes a stub that returns true, and React Native starts once per window scene.

The full change is four files: AppDelegate.swift, a new SceneDelegate.swift (added to the Xcode target), a UIApplicationSceneManifest entry in Info.plist pointing at $(PRODUCT_MODULE_NAME).SceneDelegate, and UIViewControllerBasedStatusBarAppearance flipped to true.

One detail if you apply the template diff as a patch: it did not apply to our real app. init and pod install had already edited Info.plist and project.pbxproj (after pod install, Info.plist already carried RCTNewArchEnabled, and the project file had an extra privacy manifest build entry), so the context lines no longer matched the template. We rebuilt the patch against the app’s own files. Expect the same in any app that has been through pod install, which is every app.

If your AppDelegate does more than start React Native (deep links, push registration, URL handling), those application(_:open:...) style callbacks need their scene equivalents; the 0.88.1 template already routes openURLContexts and continue userActivity through RCTLinkingManager in SceneDelegate.

The checklist

  1. On your current React Native: npm install worklets 0.13.1 and Reanimated 4.7.1 in one command, pod install, build both platforms.
  2. Search for Swipeable, DrawerLayout, gestureHandlerRootHOC and createNativeWrapper; then move Gesture Handler to 3.x and build.
  3. Move react-native-screens and safe-area-context; build.
  4. Set react-native, react and every @react-native/* package to 0.88.1 in package.json, delete node_modules and package-lock.json, install, pod install, then check Podfile.lock and run pod update React-Core-prebuilt if it still shows the old version.
  5. Apply the iOS scene changes by hand or rebuild the template patch against your own Info.plist and project file; move any URL or user-activity handling into SceneDelegate.
  6. Build both platforms and launch the app before touching anything else.

What this post does not cover: a physical device, gesture behaviour under a real finger, and app code beyond one screen. Treat the timings as one clean build each on an M1 with 16 GB, not as a forecast for a large app.

Made by the team behind this post

Apps from our studio

  • Goes with this post

    Cardigami

    Pop-up greeting cards that rise out of the fold on iPhone Duo.

    iPhone · App Store

    Get
  • Goes with this post

    BMDB.fun

    Your Bollywood world at a glance, with links straight to the OTT app that streams each film.

    Android TV · Web · Mobile

    Get
  • Nix

    The Mac uninstaller that finds what the Trash leaves behind: caches, logs, derived data and saved states.

    macOS

    Get
  • OneClick QuitAll

    Quit every running app in one click. See memory and CPU first.

    macOS · Mac App Store

    Get

Need this built? Let’s talk.

We build and run apps for Mac, TV, mobile and the web, and write about what we learn.