Expo Go vs. Dev Client: Handling Custom Native Code

Expo Go only supports built-in SDK APIs. If your React Native project needs custom native code or third-party native libraries, you must build a custom development client using EAS Build or npx expo run.

When Expo Go Fails: The Native Code Threshold

If your React Native project requires a third-party native library or custom native code not included in the standard Expo SDK, Expo Go will fail to load the application. The immediate takeaway is this: You must transition from Expo Go to a custom development client build to access your required native modules.

Diagnostic Decision Table

Symptom	Root Cause	Required Action
App crashes on startup in Expo Go	Custom native module dependency present	Build a development client
`requireNativeComponent` fails	Native code not bundled into the client	Build a development client
`npx expo-doctor` reports native issues	Missing configuration (e.g., bundle identifiers)	Configure `app.json` and rebuild

Ordered Checks for Native Dependency Issues

Inspect Dependencies: Review `package.json` for any libraries known to require native linking (e.g., Bluetooth, specific camera integrations). Check if these are supported by your current Expo SDK version.
Run Doctor: Execute npx expo-doctor in the project root. This tool validates configuration against the SDK requirements.
Configure Identifiers: Ensure ios.bundleIdentifier and android.package are present in app.json. These are mandatory for custom native builds.
Build Client: Use EAS Build or npx expo run:android/npx expo run:ios to generate the development client, installing it via npx expo install expo-dev-client.

Fixes Tied to Findings

If the issue is a missing native dependency, the fix is not just installing the package, but rebuilding the native shell. Pure JavaScript updates can use EAS Update, but native code changes necessitate a full client rebuild.

Concrete Example: If integrating a custom biometric module, simply installing the NPM package is insufficient. You must run npx expo run:ios. This process compiles the native Swift/Objective-C code alongside your JavaScript bundle into a deployable client, which Expo Go cannot handle.

Escalation Criteria

If the development client builds successfully but the custom native code still fails to initialize, the problem is likely a version mismatch. Verify that the sdkVersion specified in app.json precisely matches the SDK version used during the development client build. expo-dev-client is not a replacement for Xcode or Android Studio when debugging low-level native crashes.

Practical Verification

To confirm the correct setup, build the development client and verify that the application launches without the Expo Go error screen, successfully executing the code path reliant on the custom native module.

Limitation: Removing a native library from package.json does not automatically remove it from an already built development client; a full rebuild is always required.

A critical detail often overlooked: installing a native package via expo install only adds the dependency to package.json. The development client's native binary must be regenerated for the new code to take effect. Without rebuilding—via npx expo run:ios or EAS Build development profile—the old native shell continues running, and the new module may silently fail or cause crashes. This rebuild step is mandatory whenever native code, config plugins, or SDK-level changes are introduced, even if expo-doctor reports no errors. Pure JavaScript updates can leverage EAS Update, but any native-layer modification demands a full client rebuild to align the JavaScript bundle with the updated native artifacts.

Expo Go vs. Development Client: When Custom Native Code Forces a Build