Adding Native Code to Expo (The Modern 'Eject')

WHY IT EXISTS The standard Expo Go app provides a huge range of native APIs, but it can't include every possible native module a developer might need. Projects often require specialized functionality, like unique hardware integrations or payment SDKs, that involve custom native code. This created a need for a way to add these modules without completely abandoning Expo's streamlined workflow.

THE MENTAL MODEL Forget the old idea of 'ejecting' as a one-way exit from the Expo ecosystem. The modern mental model is additive, not destructive. You are not leaving Expo; you are creating a custom, personalized version of the Expo Go app, called a 'development build,' that includes the specific native libraries your project requires. You build this custom client once, then develop inside it, retaining much of the fast refresh experience.

HOW IT WORKS When you need to add a library with custom native code (Java/Kotlin on Android, Swift/Objective-C on iOS), you first install it like any other package. Then, instead of using the generic Expo Go app, you use Expo Application Services (EAS) Build to create a development build. This process compiles an installable app (.apk or .ipa) that bundles your new native dependencies. For libraries that require changes to native project files (like AndroidManifest.xml), you use 'config plugins' to script these modifications, avoiding manual and error-prone edits.

WHEN TO USE IT Use this workflow whenever your project depends on a React Native library that includes native code not already present in the Expo SDK. This is common for features like Bluetooth, NFC, specialized payment processors, or health data kits. If a library's installation instructions mention linking or modifying native Android/iOS project files, it's a candidate for this process.

WHEN NOT TO USE IT If a library is pure JavaScript or if the functionality you need is already available through a module in the Expo SDK, you do not need to create a development build. The Expo SDK libraries are tested to work together, ensuring smoother upgrades. Sticking to the standard SDK when possible simplifies maintenance.

ONE CANONICAL EXAMPLE A developer wants to add a third-party facial recognition library that has its own native Android and iOS components. Instead of 'ejecting,' they install the library and its config plugin. They then run an EAS command to create a development build. After installing this custom build on their test device, they can write JavaScript that calls the facial recognition library, with full access to its native features, while still using Expo's core development tools.