React Native Native Module Compatibility Guide: Expo, Fabric, TurboModules, and Autolinking
native modulesExpoFabricTurboModulesautolinking

React Native Native Module Compatibility Guide: Expo, Fabric, TurboModules, and Autolinking

RReact Native Store Editorial Team
2026-11-17
8 min read

A practical worksheet and decision process for checking Expo, Fabric, TurboModules, autolinking, and native toolchain compatibility.

Choosing a React Native native module is a compatibility decision, not just a package installation task. This guide gives you a repeatable way to check React Native and Expo versions, workflow requirements, New Architecture support, iOS and Android toolchains, and autolinking behavior before a dependency reaches production.

Overview

A package can look well maintained and still be a poor fit for a particular application. Native modules connect JavaScript or TypeScript code to platform-specific implementations, so their compatibility depends on more than the version shown in a package registry. Your project may use Expo managed tooling, a development build, or a fully native React Native workflow. It may have Fabric and TurboModules enabled, while the package still expects the legacy architecture. iOS deployment settings, CocoaPods, Android Gradle configuration, or manual linking instructions can also change the outcome.

The safest approach is to evaluate compatibility in layers:

  1. Framework: Confirm the package supports the React Native version used by the project.
  2. Workflow: Check whether it works with Expo Go, an Expo development build, prebuild, or a bare native project.
  3. Architecture: Identify whether Fabric, TurboModules, or the legacy architecture is supported and tested.
  4. Platforms: Verify iOS and Android support, minimum deployment targets, and required native tools.
  5. Integration: Confirm that autolinking, config plugins, pods, Gradle settings, and permissions are handled correctly.
  6. Maintenance: Review release activity, issue quality, migration notes, and evidence of testing against current project versions.

Use this process for UI libraries, analytics SDKs, payment integrations, storage adapters, camera modules, navigation libraries, and other React Native app development tools that include native code.

Compatibility decision table

QuestionGood signalRisk signalDecision
Does the package document your React Native version range?Supported versions and upgrade notes are clear.Only vague statements such as “latest React Native.”Test before adoption.
Does it support your Expo workflow?There is a maintained config plugin or documented development-build path.Instructions require manual native edits without Expo guidance.Do not assume Expo Go compatibility.
Is the New Architecture supported?Fabric or TurboModule status is documented and tested.Open issues report crashes or missing exports with the architecture enabled.Use an isolated proof of concept.
Does autolinking work?The package uses standard native module discovery and documents exceptions.Manual linking is required or duplicate registration is common.Inspect native projects before merging.
Are iOS and Android requirements clear?Minimum targets, permissions, pods, and Gradle requirements are listed.Installation fails until undocumented settings are added.Budget integration time and verify both platforms.
Is the project maintained?Recent releases, responsive issue handling, and migration documentation.Unresolved build failures or stale compatibility claims.Identify a fallback or avoid adoption.

How to estimate compatibility

Compatibility cannot be reduced to a single universal score, but a lightweight worksheet makes decisions consistent across a team. Record the following for every candidate native module:

  1. Project baseline: React Native version, Expo SDK or workflow, package manager, Node version, iOS deployment target, Android compile and target settings, and whether the New Architecture is enabled.
  2. Package baseline: package version, peer dependencies, native platforms, required permissions, config-plugin status, and installation method.
  3. Architecture status: legacy architecture, Fabric, TurboModule, or an explicitly documented combination. Treat an absence of documentation as “unknown,” not “supported.”
  4. Native integration surface: pod dependencies, Gradle plugins, manifest changes, plist entries, custom build phases, environment variables, and generated files.
  5. Evidence: official compatibility notes, example applications, CI configuration, release notes, issue discussions, and a local development-build test.

For a simple internal estimate, classify each category as green, yellow, or red. Green means the requirement is documented and verified. Yellow means it is plausible but needs testing or a project-specific adjustment. Red means the module conflicts with a confirmed project requirement. A package with several yellow categories may still be usable, but it should not be treated as a drop-in dependency.

Package-evaluation worksheet

Copy this checklist into an issue or architecture decision record:

  • Project React Native version: ______
  • Expo SDK and workflow: ______
  • New Architecture enabled: yes / no / planned
  • Required platforms: iOS / Android / both
  • Package version evaluated: ______
  • Peer dependency result: pass / warning / fail
  • Expo Go support: confirmed / unavailable / not applicable
  • Development-build support: confirmed / unverified / unavailable
  • Fabric support: confirmed / unverified / unsupported
  • TurboModule support: confirmed / unverified / unsupported
  • Autolinking result: pass / warning / manual work required
  • iOS pod installation result: pass / warning / fail
  • Android Gradle build result: pass / warning / fail
  • Permissions and native configuration reviewed: yes / no
  • Fallback package or removal plan: ______

This worksheet separates “the package appears compatible” from “the package has passed in our actual build.” That distinction is especially important for a React Native development platform using multiple build profiles or separate staging and production configurations.

Inputs and assumptions

Before installing a native module, establish which inputs are fixed and which may change during the project. The most important assumptions are:

Expo workflow

Do not treat Expo support as a single yes-or-no property. A package may be unavailable in Expo Go but work in a custom development build. Another may require a config plugin so native changes are applied during prebuild. A package that works in a bare project may need additional configuration in an Expo-based application. Confirm the exact workflow your team will build and distribute.

New Architecture

Fabric changes how native views integrate with React Native, while TurboModules affect the native module interface and loading model. A package can support one area, both, or neither. Check whether support is officially documented, whether it is enabled by default in your project, and whether the package's example or CI setup tests that path. If your team plans to migrate architecture later, record that as a future compatibility requirement rather than postponing the check.

Autolinking

Autolinking reduces manual native configuration, but it does not eliminate all integration work. Packages can require a config plugin, a pod install, a Gradle property, a permission declaration, or a platform-specific setup step. Duplicate manual linking can also create build errors when a package is already discovered automatically. Follow the package's current installation instructions and inspect the native project after installation.

Toolchain and platform targets

Native compatibility is also constrained by the versions accepted by your local and CI toolchains. Record the Xcode and CocoaPods setup used for iOS, and the Android SDK, Gradle, and Java configuration used for Android. Check minimum deployment targets and required permissions before committing to the dependency. A module that passes JavaScript tests can still fail during pod resolution or Android compilation.

Maintenance risk

Maintenance signals are inputs, not guarantees. Review the time since the last relevant release, the clarity of migration notes, the quality of issue responses, and whether pull requests or example applications reflect current React Native patterns. Look specifically for unresolved reports involving your architecture and platform combination. If compatibility information is missing, increase the amount of local testing rather than filling the gap with assumptions.

Worked examples

Example 1: Testing a module in an Expo development build

  1. Create a small branch or proof-of-concept screen rather than adding the module directly to a feature branch.
  2. Install the package using the documented command and inspect its peer dependencies.
  3. Check whether a config plugin is provided or required. If so, add it to the project configuration and review the generated native changes.
  4. Regenerate or update the native project according to the team's Expo workflow.
  5. Build a development client for both required platforms. Do not use a JavaScript-only preview to validate native functionality.
  6. Exercise the module's primary operation, permission flow, error path, and app restart behavior.
  7. Run the same build through CI if native configuration is generated there.

If the module works only after undocumented native edits, record those edits and decide whether they are stable enough for the team's upgrade process. A successful local build is evidence of compatibility for that project state, not a permanent guarantee.

Example 2: Diagnosing an iOS pod failure

First, capture the first meaningful error rather than the final summary. Then compare the package's pod requirements with the project's deployment target and existing native dependencies. Check for duplicate pod declarations, incompatible subspecs, stale generated files, and changes required by the package's installation notes. Re-run dependency installation using the repository's normal process, then build the app from the same workspace used in CI. If the failure occurs only after enabling the New Architecture, test the package in an architecture-disabled branch to isolate the cause; do not treat that workaround as a final compatibility result.

Example 3: Diagnosing an Android Gradle failure

Identify whether the error comes from dependency resolution, a missing Android SDK level, a Gradle plugin mismatch, Java configuration, manifest merging, or native code compilation. Compare the failing module's requirements with the application's Gradle configuration. Check for duplicate classes, conflicting transitive dependencies, and permissions or activities that must be declared. Build a clean debug variant after each material change, then repeat with the project's release-oriented configuration if the module affects production-only code paths.

Native-module installation checklist

  • Read the package's installation and migration notes for the exact version.
  • Confirm the React Native, Expo, iOS, and Android requirements.
  • Confirm Fabric and TurboModule status for the selected architecture.
  • Install once using the documented path; avoid adding manual linking without a reason.
  • Run pod installation and a clean Android build when native files change.
  • Verify permissions, entitlements, manifest entries, and config-plugin output.
  • Test cold start, reload, background or permission transitions, and failure handling.
  • Record the tested package version and build environment in the worksheet.

When to recalculate

Revisit the compatibility worksheet whenever one of its inputs changes. That includes a React Native or Expo upgrade, a package major release, a New Architecture migration, a new iOS or Android deployment target, a change to Xcode or Android build tooling, or a move from local builds to a different CI/CD environment.

A quarterly dependency audit is a practical minimum for teams with many native packages, while active projects should review compatibility during each planned framework upgrade. Recalculate sooner when a build failure appears after an otherwise unrelated dependency update, when crash reports point to a native integration, or when a package's documentation changes its installation path.

Keep the result actionable: archive the package version tested, attach build logs for failures, note any manual native changes, and name a fallback option. Before merging a native dependency, require a development-build test on every supported platform and a clear owner for future upgrades. This turns React Native native module compatibility from a one-time guess into a repeatable part of dependency management.

For related workflow decisions, compare React Native testing tools, review the React Native CI/CD guide, and use the crash reporting and monitoring guide when a native integration reaches production.

Related Topics

#native modules#Expo#Fabric#TurboModules#autolinking
R

React Native Store Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.