React Native Version Compatibility Matrix: Expo, React, Hermes, and Navigation

Overview

A React Native version compatibility matrix is less about memorizing exact versions and more about understanding dependency relationships. In most projects, the important question is not simply, “Can I upgrade React Native?” It is, “If I move one layer, which other layers must move with it?” That is where many upgrade attempts fail.

For a typical app, the stack often includes these linked parts:

• React Native, which defines the core runtime, native bridge behavior, platform support, and build expectations.
• React, which must align with the React Native release you are using.
• Expo SDK, if your app is managed with Expo or uses Expo modules, which usually pins a supported React Native baseline.
• Hermes, the JavaScript engine used by many React Native apps for startup and runtime performance.
• React Navigation and related libraries, which depend on gesture handling, screens, safe area handling, animation, and platform integration.
• Native modules, including notifications, auth, analytics, camera, maps, speech, or any custom native integration.

The point of a compatibility matrix is to record which combinations are known to work in your app, not only in the ecosystem at large. Official support ranges matter, but local reality matters more. Two teams can be on the same React Native version and have very different upgrade risk because one app uses only basic UI while the other depends on advanced navigation, push notifications, background tasks, and several native SDKs.

A simple matrix can live in your repository as a markdown file or internal docs page. At minimum, track:

• App version or branch
• Expo SDK version, if applicable
• React Native version
• React version
• Hermes enabled or disabled
• React Navigation major version
• Key native dependencies and their versions
• Build status for iOS and Android
• Test status for debug and release builds
• Known caveats or temporary workarounds

This is especially useful for teams comparing Expo vs React Native CLI because the upgrade path differs. Expo usually gives you a more guided compatibility envelope, while a bare React Native app gives you more flexibility but also more responsibility for native alignment. Neither is automatically easier in every case; they simply shift where compatibility decisions happen.

If you want the matrix to stay useful, avoid treating it as a static chart pasted into a wiki once per year. Treat it as an operational document tied to real builds, release notes, and upgrade experiments. The value comes from maintenance.

What a useful matrix looks like in practice

The best version matrix is readable at a glance. It should help a developer answer three questions quickly:

1. What stack are we running today?
2. What stack are we testing next?
3. What changed the last time something broke?

One practical pattern is to keep two tables:

• Current production baseline: the exact versions in the release branch.
• Upgrade candidates: the combinations being evaluated in a feature or maintenance branch.

That framing makes the matrix useful for both planned upgrades and emergency responses. If a platform hotfix or store requirement forces a quick adjustment, your team can compare known-good baselines instead of reconstructing dependency history from package diffs alone. That becomes even more important when preparing for fast-moving platform changes, as discussed in our guide to React Native iOS hotfix readiness.

Maintenance cycle

The most reliable compatibility strategy is a light, repeated review cycle. You do not need to upgrade everything continuously, but you do need a habit for checking whether your current stack is drifting into a harder future migration.

A manageable maintenance cycle usually includes four stages.

1. Baseline the current app

Start by documenting the versions you actually ship. This sounds obvious, but many teams track only package.json and forget that compatibility also depends on native project settings, lockfiles, Gradle changes, CocoaPods state, and feature flags such as Hermes enablement.

For each release branch, capture:

• Node and package manager version used by CI
• Expo SDK or bare React Native version
• React and React Native package versions
• Navigation stack versions
• Core native module versions such as notifications, auth, or media libraries
• Android compile and target configuration as applicable
• iOS deployment target as applicable
• Whether Hermes is enabled in both platforms
• Any patches applied locally

This baseline prevents confusion during debugging. If Android release builds fail only on CI, but local debug builds work, the issue may be in build tooling rather than React Native itself.

2. Review upstream change points

On a scheduled basis, review the upstream projects that define your compatibility boundaries. For many teams, these are:

• Expo SDK release notes
• React Native release notes
• React Navigation major and minor release guidance
• Key native module changelogs
• Build tool changes that affect Android and iOS compilation

You do not need to chase every minor release immediately. The goal is to identify whether a future upgrade will be routine, moderate, or disruptive. A patch release in a UI library is different from a major Expo SDK change that shifts your supported React Native baseline.

3. Test one layer at a time

Compatibility work becomes fragile when several major layers move together. If possible, isolate changes:

• First update Expo SDK or React Native baseline.
• Then align React and Hermes behavior.
• Then update navigation and animation libraries.
• Then validate native modules with device-level features such as camera, notifications, and auth.

This staged approach helps you identify the real fault line. If you upgrade everything in one branch, a crash in navigation transitions might be caused by gesture handling, Hermes behavior, a screens package mismatch, or a stale native build artifact. Narrowing the change surface matters.

4. Record outcome, not just intent

Many internal upgrade notes list what a team planned to do, but not what actually happened. A compatibility matrix becomes valuable when it records concrete outcomes such as:

• Build succeeds on iOS debug and release
• Build succeeds on Android debug and release
• Deep linking verified
• Push notifications verified
• Hermes enabled with no observed startup regressions
• Navigation transitions working on both platforms
• Known issue: one package requires a temporary pin

That history saves time the next time someone searches for “react native upgrade guide” inside your own organization.

A practical maintenance rhythm

For most teams, a quarterly review is a reasonable default, with shorter checks when the app is in active release motion. Monthly review can make sense for apps with heavy native integrations or app store compliance pressure. The key is consistency. Small, regular review cycles are easier than one large annual migration.

Signals that require updates

A compatibility matrix should not change only when someone has spare time. It should change when clear signals appear. These signals help you decide when to revisit the document and when to open an upgrade branch.

1. An upstream framework release changes the supported baseline

This is the clearest trigger. If Expo publishes a new SDK or React Native introduces changes that affect your React pairing, JavaScript engine behavior, or native build requirements, your matrix should reflect that. Even if you do not upgrade immediately, note the new supported path and any constraints.

2. A library introduces a major version bump

Navigation, animations, state libraries, push notifications, and auth SDKs often shift peer dependency expectations. If React Navigation or a related package changes its major version, that may also affect gesture handling, screens, reanimated, or safe area libraries. Your matrix should show those dependencies as a cluster, not as unrelated rows.

3. CI starts failing after a previously harmless dependency refresh

This often indicates hidden compatibility drift. Maybe your lockfile changed, a native toolchain dependency moved, or a package now expects a newer React Native baseline. If CI becomes unreliable after routine maintenance, update the matrix with the failing combination and your workaround. Compatibility knowledge is most valuable when something is broken.

4. A device feature behaves differently in release builds

Many compatibility issues hide behind successful development builds. Notifications may fail only in signed builds. Hermes-related behavior may differ between debug and release. Navigation transitions may appear smooth locally but regress on lower-end devices. Any release-only divergence is a reason to revisit your recorded compatibility assumptions.

If your app includes performance-sensitive features, pair matrix maintenance with targeted runtime review. Our article on adaptive frame targets in React Native is a useful companion when compatibility and performance concerns overlap.

5. Search intent shifts within your team

This article is built as a maintenance hub because version advice goes stale. A good sign that your matrix needs attention is when teammates keep asking the same questions in chat or pull requests:

• Which Expo SDK are we targeting next?
• Can we enable Hermes safely now?
• Which React Navigation version matches our stack?
• Why does this native module install fine but fail at runtime?
• Should we stay on Expo or eject for this integration?

If the same confusion repeats, your compatibility guide is not current enough.

Common issues

Most compatibility failures in React Native app development are patterns, not surprises. Knowing the common breakpoints will make your matrix more useful and your upgrade plans more realistic.

Expo SDK and bare React Native assumptions get mixed together

Teams sometimes read advice meant for a bare React Native app and apply it directly to an Expo-managed project, or the reverse. That creates confusion around native configuration, package installation, and runtime support. If your project uses Expo, your matrix should clearly distinguish:

• Expo-managed workflow assumptions
• Prebuild or config plugin requirements
• Bare workflow overrides or custom native changes

That distinction is crucial for libraries that touch native permissions, background behavior, media, speech, or notifications.

Hermes is treated as a toggle instead of a compatibility decision

Hermes can improve app behavior in many cases, but enabling it is not just a performance checkbox. It affects JavaScript engine expectations, debugging workflows, stack traces, memory behavior, and sometimes third-party library behavior. Your matrix should note whether Hermes is enabled on each platform and whether your critical flows have been tested under release conditions.

This is especially important for apps with heavier interaction or media processing, such as voice features. If you are working on speech or offline model integration, related guidance in on-device speech for React Native and voice-first mobile workflows can help you think through runtime tradeoffs beyond package versions alone.

Navigation issues are blamed on navigation alone

React Navigation compatibility problems often come from adjacent packages. A navigation stack may depend on screens, gestures, animations, safe area handling, linking behavior, and platform-specific setup. When you track “react native navigation compatibility,” include the supporting packages as one tested unit. Otherwise, you can end up upgrading navigation successfully on paper while still shipping broken back gestures or transition animations.

Native module support is assumed from install success

If a package installs cleanly, that does not prove compatibility. Native modules can compile and still fail at runtime because of initialization order, platform permission changes, app lifecycle assumptions, or unsupported React Native internals. Mark modules as compatible only after real device tests cover the features you actually use.

Release signing and deployment settings are left out of the matrix

This is one of the most costly omissions. Some apps appear fully compatible until Android signing, iOS archiving, or store submission steps begin. If your app has a history of release friction, include deployment notes directly in the matrix or link them from the same document. Compatibility is not only about coding; it includes successful packaging and delivery.

Teams skip rollback planning

Every upgrade branch should answer one practical question: if this release candidate slips, what is our fallback? Keep a known-good baseline, keep the lockfile tied to that baseline, and record the smallest safe rollback path. The ability to retreat cleanly is part of compatibility maintenance, not a separate concern.

When to revisit

The best time to revisit your React Native version compatibility matrix is before it becomes urgent. A light review habit keeps upgrades small and avoids the brittle situation where Expo, React Native, navigation, and several native modules all need major changes at once.

Use this practical checklist to decide when to update the matrix and what to do next.

Revisit on a scheduled review cycle

• Review the matrix at least quarterly.
• Confirm that the documented production baseline still matches the release branch.
• Check whether upstream projects changed recommended upgrade paths.
• Archive rows for combinations your team no longer supports.

Revisit before major app work begins

• Starting a redesign with a new navigation flow
• Adding push notifications or background tasks
• Integrating authentication or a payment SDK
• Adding device-intensive features such as speech, maps, or camera flows

These projects often expose compatibility debt that basic CRUD screens do not.

Revisit after any significant build or runtime regression

• CI failures after dependency refresh
• Release-only crashes
• Navigation regressions on one platform
• Startup or memory regressions after enabling Hermes
• Native module errors after a React Native upgrade

When one of these appears, do not just patch forward. Update the matrix with the failing combination, the fix, and the confidence level of the result.

Revisit when your tooling strategy changes

If your team is considering a workflow shift between Expo-managed, prebuild, and bare React Native, revisit the matrix first. The document should help answer whether your native requirements still fit your current setup, and whether a tooling change would reduce or increase compatibility overhead.

Keep a standing action list

To make this article worth revisiting, keep a short recurring action list in your own repository:

1. Document the current shipped stack.
2. List one next-step upgrade path only.
3. Test iOS and Android in debug and release.
4. Verify navigation, notifications, auth, and any business-critical native feature.
5. Record caveats, pins, patches, and rollback notes.
6. Set the next review date.

That is the practical heart of a durable react native upgrade guide. A compatibility matrix is not a static spreadsheet for the whole ecosystem. It is a living operational record for your app, your workflow, and your chosen stack. If you maintain it with discipline, Expo SDK upgrades become easier to scope, Hermes decisions become less speculative, navigation changes become less fragile, and the next upgrade conversation starts from evidence instead of guesswork.