Upgrading to React Native 0.87: what broke, how I fixed it, and what Metro really gained

React Native 0.87 shipped on 11 August 2026 with the Strict TypeScript API on by default, a faster Metro, experimental Swift Package Manager support and Android Gradle Plugin 9. Most write-ups summarise the release notes. I wanted real numbers, so I built a small store-audit app on 0.86.3, deliberately using the APIs 0.87 changes, upgraded it to 0.87.1 and recorded everything that broke.

Everything is in a public repo, one commit per step, so you can reproduce it.

What changed in the template?

I applied the official template diff from the Upgrade Helper. It's small, and nothing on iOS changes:

The two AGP 9 opt-outs keep the old Kotlin and DSL behaviour for now. They go away in AGP 10, so treat them as a reminder, not a fix:

android.builtInKotlin=false
android.newDsl=false

Then one install with the new versions, and a type check.

16 TypeScript errors in an app that compiled yesterday

On 0.86.3, tsc --noEmit was clean. On 0.87.1 it reported 16 errors in 6 files. They fall into three groups.

Types that were renamed or removed

ViewProperties and the other *Properties aliases are gone; use the *Props names. NativeMethods is replaced by HostInstance:

- import type { NativeMethods } from 'react-native';
- import type { ViewProps } from 'react-native/Libraries/Components/View/ViewPropTypes';
+ import type { HostInstance, ViewProps } from 'react-native';
 
- export function measureInWindow(node: NativeMethods | null) {
+ export function measureInWindow(node: HostInstance | null) {

That deep import into react-native/Libraries is the change most codebases will hit: under the Strict API it's a hard error ("Cannot find module"). Losing NativeMethods cost 4 more errors on its own, because the measureInWindow callback's parameters lost their types.

Refs need the new instance types

useRef<View>(null) and useRef<TextInput>(null) no longer type-check. Components are typed as functions now, so a ref holds an instance type instead:

- const notes = useRef<TextInput>(null);
- const banner = useRef<View>(null);
+ const notes = useRef<TextInputInstance>(null);
+ const banner = useRef<ViewInstance>(null);

Both types come from react-native (import { type TextInputInstance, type ViewInstance } from 'react-native').

useColorScheme() can return null

It used to return 'unspecified' when there was no preference. Now it returns null, and comparing against 'unspecified' is a type error:

- export function describeScheme(scheme: ColorSchemeName) {
-   if (scheme === 'unspecified') return 'Following the system';
+ export function describeScheme(scheme: ColorSchemeName | null) {
+   if (scheme === null) return 'Following the system';

Setting the scheme changed too: Appearance.setColorScheme('unspecified') is deprecated in favour of 'auto'. It still compiles, so a type check won't flag it.

What the opt-out flag actually hides

0.87 keeps a temporary way back to the old types, through 0.88 only:

{
  "extends": "@react-native/typescript-config",
  "compilerOptions": {
    "customConditions": ["react-native", "react-native-legacy-deep-imports"]
  }
}

With it, my 16 errors dropped to 6. The 6 that remain are APIs that were removed, not just retyped, and no flag brings them back. So the opt-out buys time for the type changes only. Since it's only available through 0.88, I'd fix everything now instead.

The ones that matter at runtime

Metro doesn't type-check, so here's how the removed APIs behave if you ship without fixing the types.

InteractionManager is gone, and that's a crash

InteractionManager isn't exported any more, so InteractionManager.runAfterInteractions(...) throws at runtime. The release notes point to requestIdleCallback:

  useEffect(() => {
-   const task = InteractionManager.runAfterInteractions(() => setItems(checklist));
-   return () => task.cancel();
+   const handle = requestIdleCallback(() => setItems(checklist));
+   return () => cancelIdleCallback(handle);
  }, []);

type IdleDeadline = { readonly didTimeout: boolean; timeRemaining(): number };
 
declare function requestIdleCallback(
  callback: (deadline: IdleDeadline) => void,
  options?: { timeout?: number },
): number;
declare function cancelIdleCallback(handle: number): void;

Two props that silently stop working

StatusBar's translucent and backgroundColor, and Modal's animated, are removed. TypeScript flags them, but nothing fails at runtime: React Native's 0.87 source no longer reads these props, so they're ignored. With edge-to-edge on by default, the status bar is already drawn over your content, so the fix is to delete them:

- <StatusBar translucent backgroundColor="transparent" barStyle={barStyle} />
+ <StatusBar barStyle={barStyle} />

For Modal, animationType already controls the animation; drop animated. While you're there, keyboardShouldPersistTaps={true} on ScrollView must become "always".

Deprecated, not removed: ImageBackground

ImageBackground still works and still type-checks, but it's deprecated. The replacement is a View with an absolutely positioned Image:

<View style={[styles.banner, style]}>
  <Image source={{ uri: bannerUrl }} style={StyleSheet.absoluteFill} />
  <Text style={styles.title}>{title}</Text>
</View>

Add overflow: 'hidden' to the container if it has rounded corners.

To find deep imports in your own code before you start:

grep -rn "react-native/Libraries" src --include=*.ts --include=*.tsx

Building on Android: AGP 9 and the opt-outs

With the template diff applied, ./gradlew :app:assembleDebug built on the first try: 8 minutes 57 seconds from cold, including Gradle downloading Android SDK Build-Tools 37 and Platform 37 by itself (no manual SDK Manager step). Two warnings are worth acting on.

The template's own MainActivity is deprecated. Even the official 0.87.1 template still passes the old fabricEnabled flag, which now does nothing because the New Architecture is always on:

- import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled
  ...
  override fun createReactActivityDelegate(): ReactActivityDelegate =
-     DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
+     DefaultReactActivityDelegate(this, mainComponentName)

AGP 9 already calls the opt-outs deprecated. The two lines the template adds to gradle.properties print The option setting 'android.builtInKotlin=false' is deprecated (and the same for newDsl). So I tried building without them. It failed in one second:

Failed to apply plugin 'org.jetbrains.kotlin.android'.
> Cannot add extension with name 'kotlin', as there is an extension already registered with that name.

AGP 9 now includes Kotlin support itself, so the separate Kotlin plugin in app/build.gradle clashes with it. Removing that one line was enough:

  apply plugin: "com.android.application"
- apply plugin: "org.jetbrains.kotlin.android"
  apply plugin: "com.facebook.react"

With both opt-outs gone and that line removed, the app built, Kotlin and C++ included, and the deprecation warnings disappeared. react-native-safe-area-context, which applies its own Kotlin plugin, built fine either way.

Metro: what "2× faster" looks like on a real app

The headline claim is that source maps are generated about 2× faster and Metro uses about half the memory, which mostly shows up when React Native DevTools loads. So I measured what DevTools waits for: the dev server's source map, requested after the bundle is built. I ran it on the demo app, and on a synthetic 2,000-screen app (about 92,000 lines of TypeScript) to see how it scales.

The speed-up grows with the size of the app: barely noticeable on a small one, close to the advertised 2× on a large one. Every 0.87.1 round beat every 0.86.3 round on source-map time and server memory, so these aren't noise. The whole server process used about 30% less memory rather than half, which makes sense: the 50% saving is in how source maps are stored, not in everything Metro holds.

Should you upgrade now?

Yes, if you're on 0.86. The type errors are mechanical, the template diff is small, and the work transfers directly to 0.88, already at release candidate 3 as I write this. Budget an afternoon for a mid-size app, plus a check of your dependencies.

Wait a little if you rely on libraries that deep-import heavily and haven't released Strict-API-ready versions, or if you can't test the edge-to-edge change on Android yet. The Android build itself is unlikely to hold you up: it worked from the template diff alone.

• Merge the template diff by hand: edgeToEdgeEnabled now defaults to true on Android.
• Drop fabricEnabled from MainActivity; even the 0.87.1 template still passes it.
• Try removing the AGP 9 opt-outs on a branch: delete the separate Kotlin plugin line and see if it builds.
• Search for react-native/Libraries imports before upgrading; they are hard errors now.
• Swap ref types to ViewInstance, TextInputInstance and friends.
• Treat useColorScheme() as possibly null, and use 'auto' instead of 'unspecified'.
• Replace InteractionManager with requestIdleCallback, and add the missing types.
• Delete StatusBar translucent/backgroundColor and Modal animated; they're silently ignored.
• Don't rely on the legacy types opt-out: it hides only the type changes, and only through 0.88.