React Native 0.87's Breaking Changes: A CTO's Upgrade Risk Map

React Native 0.87’s breaking changes come down to four things. Stricter, auto-generated type definitions are now the default, so shortcuts that reached into the framework’s internal files now fail. The minimum tooling jumps to newer versions of Node, Android’s build system, and Kotlin. A new iOS build method arrives as a preview. And a batch of old, deprecated features is deleted outright.

That’s the short answer a search engine can quote. The longer answer — the one that decides your quarter — is about which of those four lands as a five-minute find-and-replace versus a two-week fight with your build pipeline (the automated system that turns code into a shippable app). Below is how to size the risk before you commit a single engineer to it.

What actually changed in React Native 0.87

Released on August 11, 2026, version 0.87 makes the Strict TypeScript API the default, updates the bundler (the tool that packages your JavaScript for the phone) from 0.84 to 0.87, and adds an experimental option to build iOS apps with Apple’s own package tool instead of the older Ruby-based one. It also raises the floor on the tools you need installed: Node.js 22.13 or newer, Android Gradle Plugin 9, and Kotlin 2.0 or above. The release shipped with 265 commits from 74 contributors, per the React Native team.

Here’s the thing a changelog won’t tell you: none of these are optional if you want to stay on a supported version. With 0.87 out, version 0.84 moves to unsupported, meaning no more security or bug fixes. So the real question isn’t whether to absorb these changes — it’s when, and how much of your team’s time it costs.

Strict TypeScript API: what breaks in your existing code

The change most likely to light up your error log is the strict typing default. React Native’s public code interface is now scoped to exactly what the framework officially exports, and the type definitions are generated straight from the source instead of hand-written. In plain terms: if any of your code or your third-party libraries reached into React Native’s internal folders — paths like react-native/Libraries/* — those shortcuts now throw a type error and have to be rewritten.

The blast radius depends on how disciplined your codebase and your dependencies have been. According to the React Native team, many apps will upgrade with few or no errors, because the strict rules have been available as an opt-in preview since version 0.80 (June 2025) and popular libraries had time to adapt. But if you lean on older or unmaintained packages that dig into those internal paths, you inherit their debt — and you can’t fix someone else’s library by editing your own code.

Two concrete gotchas. First, references to components now use dedicated types (like ViewInstance and TextInputInstance), so any code that typed those the old way needs updating. Second, deprecated type aliases such as ViewProperties are gone — you use the *Props versions instead. There’s an ESLint fixer and even an agent-driven migration skill to automate much of it, plus a temporary escape hatch: adding a react-native-legacy-deep-imports setting to your TypeScript config buys you time. But that opt-out only survives through version 0.88, after which the legacy types disappear for good.

If you’re a team with a large app and a pile of native dependencies, the smart move is to run the upgrade in a branch, count the errors, and only then estimate the work. The error count is your effort estimate. This is exactly the kind of upgrade where a short React Native engineering engagement pays for itself, because the cost is knowable up front once someone runs the numbers.

The toolchain jump: Node 22, Gradle 9, and Kotlin 2.0

The quiet risk in 0.87 isn’t your app code — it’s the machines that build it. The new minimums (Node.js 22.13, Android Gradle Plugin 9, Kotlin 2.0+, and a bumped Android compile target of SDK 37) mean your continuous integration setup — the servers that build and test every code change automatically — needs its base images and installed versions updated before anything compiles. A developer’s laptop might already be current; your build server usually isn’t.

Android Gradle Plugin 9 is the sharp edge here. It’s a major release with its own breaking changes to how Android builds work, and the React Native team’s own recommendation is to opt out of two of its new behaviors — the built-in Kotlin handling and the new configuration syntax — by adding android.builtInKotlin=false and android.newDsl=false to your Gradle properties. That’s a telling signal: even the maintainers are treating parts of Gradle 9 as not-yet-ready, and those opt-outs themselves go away in a future release. So you’re buying stability now and signing up for another round of work later.

Picture a team that ships through an automated pipeline every day. The upgrade doesn’t just touch code — it touches the Docker images, the cached dependencies, and the signing setup that produce your release builds. Budget for a broken pipeline for a day or two even if the app code itself is clean, because that’s where the surprises hide.

Swift Package Manager on iOS: preview, not production

The most future-facing change is experimental support for Swift Package Manager, Apple’s native way of managing iOS dependencies, as an alternative to CocoaPods (the older Ruby-based tool most React Native apps use today). The appeal is real: the new path needs only Xcode — no Ruby, no Bundler, no CocoaPods — and after a one-time setup command, you never run a pod install step again when dependencies change. The project detects the change and re-links automatically.

But the React Native team is explicit: CocoaPods remains the default and the supported path, and you should not use the Swift path in production yet. The commands and layout may still change. There is one breaking change that touches everyone regardless, though — a header import rule. If your native code imports a React Native header without its namespace, like #import <RCTAppDelegate.h>, it now must read #import <React/RCTAppDelegate.h>. Small, mechanical, but it will stop an iOS build cold until fixed.

For now, treat Swift Package Manager as a preview to test on a side branch, not a migration to schedule. The teams that benefit from experimenting early are those planning a long React Native investment who want to shape their tooling before it hardens. Everyone else can wait a release or two.

Should you upgrade to React Native 0.87 now, later, or skip it?

You can’t skip it indefinitely — 0.84 is now unsupported — but you can time it. Upgrade now if you’re on a recent version, your dependencies are actively maintained, and you have CI capacity to absorb the toolchain jump; the strict typing migration is mostly automated and the payoff is a stable API that stops breaking on React Native’s internal changes. Wait a cycle if you’re several versions behind or depend on libraries that haven’t adopted strict types, since you’d be doing two hard jobs at once. Either way, don’t wait past 0.88, when the legacy type escape hatch is removed.

On the build-versus-buy question — meaning handle it in-house versus bring in outside help — the honest read is this. If your app is small, your dependencies are current, and you have an engineer who’s done a React Native upgrade before, do it yourself; the migration guide and automated fixers cover most of it. Bring in help when the error count from the strict-types branch is high, when your build pipeline is fragile or undocumented, or when the upgrade sits on the critical path to a release you can’t slip. The value an outside team adds isn’t typing skill — it’s a predictable timeline on the one part of this that’s unpredictable: the CI and native-build breakage. If you’re still weighing the framework itself, our breakdown of React Native versus Flutter covers when neither is the right call.

A practical migration checklist

Run these in order, and stop to reassess after step three:

• Update your local and CI environments to Node.js 22.13+, Android Gradle Plugin 9 (with the two recommended opt-out flags), and Kotlin 2.0+.
• Create an upgrade branch and use the React Native Upgrade Helper to see the exact file diffs for your version jump.
• Run the build and count the strict-typing errors. This number is your effort estimate — decide in-house-versus-help here.
• Apply the ESLint fixers and the migration skill to clear the mechanical type errors; add the header namespace prefix on iOS.
• Audit third-party libraries for internal deep imports you can’t fix yourself, and use the legacy opt-out only as a temporary bridge.
• Fix the CI pipeline separately from the app code, and budget a day or two for broken release builds even if the code compiles locally.

If step three returns a scary number, that’s your cue to book a React Native upgrade audit rather than guess at the timeline. And if the exercise has you rethinking cross-platform altogether, our native-versus-cross-platform comparison lays out the trade-offs honestly.

FAQ

Q: What are the main breaking changes in React Native 0.87? A: The biggest is the Strict TypeScript API becoming default, which turns shortcuts into React Native’s internal folders into errors. The minimum tooling also jumps to Node.js 22.13, Android Gradle Plugin 9, and Kotlin 2.0+. Several deprecated APIs — including InteractionManager and the useTurboModules flag — are removed entirely.

Q: Do I have to migrate to the Strict TypeScript API immediately? A: No. React Native 0.87 keeps a temporary opt-out you enable by adding react-native-legacy-deep-imports to your TypeScript config. But per the React Native team, that opt-out only works through version 0.88, and the legacy types are removed after that — so it buys time, not a permanent exit.

Q: Is Swift Package Manager support ready for production in 0.87? A: No. The React Native team ships it as experimental and opt-in, with CocoaPods remaining the default supported path. The commands and layout may change in later releases, so treat it as a preview to test on a branch rather than a production migration.

Key Takeaways

• The error count from a strict-types trial branch is your single best estimate of upgrade effort — run it before committing a timeline.
• Budget separately for your build pipeline; the toolchain jump to Gradle 9 and Node 22 often breaks CI even when app code is clean.
• The legacy-types opt-out expires after version 0.88, so any team using it now should schedule the real migration before then.
• Keep Swift Package Manager on a side branch until the tooling stabilizes; only the header-import fix is mandatory for everyone in 0.87.
• Bring in outside help when the upgrade sits on a release critical path or your dependencies are unmaintained — the risk is timeline, not skill.