Search across all documentation pages
When to write native code versus reach for an Expo SDK package. These rules keep teams on the supported path for Expo SDK 57 and React Native 0.86, minimize CNG/prebuild surprises, and ensure native dependencies ship with matching dev-client and store binaries.
ios/ and android/ on every prebuild.npx expo-doctor after every native dependency change.Search Expo SDK packages first: expo-camera, expo-location, expo-notifications, and 100+ modules ship with SDK 57 native binaries - prefer them over random npm native wrappers.
npx expo install expo-camera - not npm install expo-camera@latest.Second choice: community module with Expo config plugin: Many libraries ship a config plugin in app.config plugins array - read their SDK 57 compatibility matrix before installing.
Third choice: Expo Modules API for thin custom native bridges: When no package exists, write an Expo module in modules/my-feature/ - autolinking and TypeScript types integrate cleanly with CNG.
npx create-expo-module@latest for the module scaffold.Last resort: bare Swift/Kotlin patches via config plugin: Hand-maintained ios/ and android/ folders are for brownfield only - standard CNG apps express changes as plugins.
Podfile that are not encoded in a plugin.Expo Go is not a native test target for custom modules: Packages not bundled in Expo Go require expo-dev-client - do not claim QA sign-off from Expo Go alone.
development EAS profile builds installable dev clients.One native change per PR when possible: Mixing a new payment SDK, camera plugin, and custom module in one merge makes bisect impossible when prebuild fails.
Always npx expo install for native deps: Resolves versions compatible with SDK 57 native binaries - compile success does not guarantee runtime stability.
npx expo install --fix then expo-doctor.package.json ranges drift from Expo's bundled versions without ADR.Register config plugins in app.config.ts: Native permissions, entitlements, and manifest entries belong in plugins - not post-prebuild manual edits.
npx expo prebuild --clean locally before merging plugin changes.Write idempotent config plugins: Running prebuild twice must not duplicate entries in Info.plist or AndroidManifest.xml.
git diff native output - should be empty the second time.Declare permissions with user-facing strings: iOS NSCameraUsageDescription and Android permission rationale - missing strings crash or reject store review.
app.config ios.infoPlist - never only in generated files.locales/ for permission strings in shipped languages.Use expo-build-properties for compile SDK and deployment targets: Centralize minSdkVersion, compileSdkVersion, and iOS deployment target - scattered Gradle edits are lost on prebuild.
Autolinking handles most linking - do not manually edit settings.gradle: Expo autolinking registers native modules - manual pod install hacks belong in plugins if truly necessary.
npx expo-modules-autolinking resolve when a module is not found.react-native instance - duplicate copies break autolinking silently.Gitignore generated ios/ and android/ under CNG: Committed native folders block SDK 57 template updates - EAS Build runs prebuild remotely.
npx expo prebuild --clean reproduces CI native projects.Rebuild dev client after every native dependency change: OTA (eas update) updates JavaScript only - new native modules require eas build --profile development.
expo-dev-client with SDK upgrades.Store builds and native changes are never OTA-only: If a JS feature requires a new native module, ship a store build first - gate JS with runtime version checks until adoption threshold is met.
expo-updates runtime version policy + feature flag for new native API.Test on physical devices for hardware modules: Camera, BLE, NFC, and push behave differently on simulators - sim-only QA misses permission and background failures.
New Architecture compatibility is explicit: RN 0.86 favors New Architecture - verify third-party native modules declare Fabric/TurboModule support or document fallback.
expo-doctor warnings.Release native handles and listeners: Long-lived SharedObject instances from Expo modules (players, sensors) need release() on unmount - leaks crash backgrounded apps.
useEffect cleanup calls module remove() or subscription remove().Custom Expo modules live in modules/ with typed JS API: Export a narrow TypeScript surface - features import @/modules/my-feature, not raw NativeModules strings.
No business logic in native code: Native layer handles platform APIs and marshaling - pricing rules and validation stay in TypeScript.
if user.isPremium duplicated from JS.Semantic versioning for internal modules: Breaking native API changes require a store build and changelog - treat modules/ like a published package.
Security review for native modules that touch secrets: Keychain wrappers, payment SDKs, and attestation libraries need security sign-off - not only mobile lead review.
UserDefaults without encryption.Prebuild in CI on native PRs: Run npx expo prebuild --clean --no-install (or full EAS build) to catch plugin failures before merge.
ADR for every custom native module and non-Expo native dependency: Status, owner, alternatives considered, New Architecture stance, and retirement trigger.
Prefer Expo Modules API for new custom bridges - autolinking, TypeScript, and config plugins integrate with CNG. Legacy RN native modules work but need more manual linking maintenance on SDK 57.
Brownfield apps with committed native dirs and a documented merge strategy. Standard greenfield Expo apps should never hand-edit generated files - use config plugins.
Yes - plugins mutate native projects at prebuild time. Run a new dev-client and store build; OTA alone is insufficient.
Check Expo docs - if the package is not in the Expo Go bundle, you need a dev build. expo-doctor may also warn about incompatible dependencies.
No - native code ships in the binary. You can ship JS that calls an existing native module OTA, but adding the module itself requires a store build.
Create a module with npx create-expo-module@latest, register it in the app's package.json workspaces or modules/ folder, and autolinking picks it up on prebuild.
Place shared modules in packages/native-feature/ with proper react-native peer deps. One app runs prebuild; the module autolinks from the workspace path Metro resolves.
Some community modules lag Fabric/TurboModule support on RN 0.86. Verify before adopting; document Old Architecture fallback in an ADR if required temporarily.
Almost never - upstream a fix or wrap with a config plugin. Forks when the maintainer is gone require an ADR with security patch ownership.
Mock at the TypeScript boundary (jest.mock('@/modules/my-feature')) with realistic return shapes. Run integration tests on device via Maestro or manual QA for hardware paths.
SDK upgrades, plugin changes, autolinking failures, and unexplained native build errors. --clean is the default recovery path on SDK 57 - not a last resort.
Plugins run on any prebuild - local and remote. Keep local prebuild reproducible so CI and laptops generate identical native projects.
The ADR names a primary owner (iOS/Android or full-stack mobile). Unowned native code is a merge blocker in mature teams.
Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (
expo~57.0.4).
Reviewed by Chris St. John·Last updated Jul 9, 2026