keepcalculator

06 Numbers and Powers

Expo Native Modules: Why Compilation Doesn’t Guarantee

Card No. 06·80181 · Updated · Standard formula, shown below

Expo native modules compile successfully, yet the app can still crash or misbehave at runtime. This article explains why a successful build is only the first step, what actually goes wrong, and how to diagnose and fix issues when your native module compiles but doesn’t work.

What Compilation Actually Checks

When you run expo run:android or expo run:ios, the build system compiles your JavaScript, native code, and dependencies into a binary. Compilation verifies syntax, type correctness (if using TypeScript), and that all symbols referenced in native code exist. It does not verify that the logic inside those functions is correct, that the native module’s assumptions match your app’s runtime environment, or that the JavaScript bridge will pass data in the format the native side expects.

Think of compilation as a spell-check: it catches typos and missing words, but not a sentence that says the opposite of what you meant. A native module can compile perfectly and still fail because of mismatched data types, threading issues, or lifecycle events that only happen at runtime.

Why a Successful Build Doesn’t Mean It Works

Here are the most common reasons a native module compiles but fails at runtime:

  • JavaScript-to-native type mismatches: You pass a string where the native code expects a number, or an object with missing keys. The bridge doesn’t enforce types; it just serializes whatever you send.
  • Threading violations: Native modules often run on a background thread. If you update UI state from a background thread, the app may crash intermittently—not at build time.
  • Missing runtime permissions: A module that accesses the camera, location, or storage may compile fine but crash when the user denies permission or when the permission isn’t declared in the app manifest.
  • Lifecycle timing: The module may expect the app to be in a certain state (e.g., after onCreate), but you call it earlier. Compilation can’t catch this.
  • Device-specific behavior: A module that works on the emulator may fail on a physical device due to different sensor availability, screen density, or OS version quirks.

How Expo Handles Native Modules

Expo has two main paths for native modules. In the managed workflow (using Expo Go or prebuild), you’re limited to modules included in the Expo SDK. In the development build workflow, you can add any native module via npx expo prebuild and then compile with Android Studio or Xcode. In both cases, the compilation step is identical to a regular React Native app—it just uses the Expo toolchain.

The key difference is that Expo’s prebuild generates the native projects for you. If you modify the native code after prebuild, you must re-run prebuild (or carefully merge changes) to avoid losing them. But even with correct native code, the JavaScript side must communicate properly through the bridge.

Common Runtime Failures and How to Diagnose Them

When a native module compiles but crashes, the error message is your first clue. Common patterns:

  • “Cannot read property ‘X’ of null” — the native module returned null because it failed to initialize, often due to a missing dependency or an unavailable system service.
  • “TypeError: X is not a function” — you’re calling a method that doesn’t exist on the module’s JS interface. This can happen if the native module’s exported methods don’t match the JS wrapper.
  • Native crash with no JS stack trace — the crash happens in native code, often due to a threading issue or an unhandled exception. Check Logcat (Android) or the device console (iOS) for the native stack trace.

To diagnose, start by isolating the module: create a minimal test screen that calls only that module’s functions. Then check the native logs. For Android, run adb logcat; for iOS, use the Xcode console. The error message usually points to the exact line in native code where the failure occurred.

How to Choose a Reliable Native Module

Before adding a native module to your Expo project, evaluate it on these criteria:

  • Maintenance status: Is the repo actively updated? Does it support the current React Native and Expo SDK versions?
  • Issue tracker: Search for “crash” or “runtime” issues. A module with many unresolved crash reports is a red flag.
  • Documentation quality: Does it clearly state platform requirements, permissions, and threading behavior?
  • Community adoption: High download counts and usage in popular apps suggest it’s been battle-tested.

Also, check the module’s app.plugin.js if it has one—Expo config plugins automate native configuration. A missing plugin means you’ll have to manually edit the native projects, which increases the chance of misconfiguration.

Comparison: Expo Go vs. Development Builds

Expo Go includes only the native modules bundled in the Expo SDK. If you use a custom native module, it won’t work in Expo Go—you’ll get an error like “Native module cannot be null.” This is expected, not a bug. Development builds (created with npx expo run:android or npx expo run:ios) include your custom native code and are the only way to test it.

The compilation process is the same for both, but the runtime environment differs. Expo Go is a generic container; a development build is specific to your app. If your module works in a development build but not in Expo Go, that’s normal. If it fails in both, the issue is likely in your JavaScript usage or the module’s configuration, not the build process.

Costs and Performance Considerations

Native modules can increase your app’s binary size, memory usage, and startup time. Each module adds native code that must be loaded at runtime. Some modules also spawn background threads or use system services, which can drain the battery if not managed properly.

Performance issues are often mistaken for compilation failures. For example, a module that works but causes janky UI may be doing heavy work on the main thread. Compilation won’t catch this; you need profiling tools like the React Native Performance Monitor or Xcode’s Instruments.

There’s also a maintenance cost: every time you upgrade the Expo SDK or React Native, you may need to update the native module. A module that compiles today may fail after an upgrade because of API changes in the native framework.

Safety and Best Practices

To minimize runtime failures with native modules:

  • Always test on a physical device — emulators don’t have the same sensors, permissions, or performance characteristics.
  • Wrap native module calls in try-catch — even if the module is well-written, it may throw an error that you can handle gracefully.
  • Check for null returns — always verify that the module’s methods return the expected data before using it.
  • Read the native code — if you can, skim the module’s source to understand its threading model and error handling.
  • Use Expo’s config plugins — they automate the native configuration and reduce the chance of missing permissions or dependencies.

Also, remember that a native module can be a security risk if it’s poorly maintained or contains malicious code. Only use modules from trusted sources, and review what permissions they request.

Frequently Asked Questions

Why does my native module compile but crash on launch?

This usually means the module fails to initialize at runtime. Check if the module requires a configuration step (like calling init() in your app’s entry file) or if it depends on another native library that isn’t linked. Also verify that the module’s native code doesn’t reference a class or resource that’s missing from your build.

How do I know if a native module is compatible with Expo?

Check the module’s documentation for Expo support. If it has an app.plugin.js or mentions “Expo config plugin,” it’s designed for Expo. Otherwise, it may work in a development build but require manual native configuration. You can also search the Expo community forums for the module name to see if others have used it successfully.

Can I use a native module in Expo Go?

No. Expo Go only includes the native modules that are part of the Expo SDK. Any custom native module will not work in Expo Go. You need to create a development build using npx expo run:android or npx expo run:ios to test your custom native code.

Why does my module work on Android but not iOS?

Platform-specific differences are common. The module may use APIs that exist only on one platform, or it may have different configuration requirements (like permissions or entitlements). Check the module’s documentation for platform-specific notes, and ensure you’ve configured both platforms correctly in your app.json or native projects.

What should I do if a native module crashes only on certain devices?

This often points to a hardware or OS version issue. The module may rely on a sensor or feature that’s not available on all devices. Test on multiple devices and check the native logs for specific error messages. You may need to add a runtime check to disable the module on unsupported devices.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →