react-native · folio
In one line: android/ is an ordinary Gradle project embedding a JS bundle:
AGP compiles Kotlin/Java (R8 shrinks it), the NDK builds C++ per ABI, the
manifest merger combines every library’s manifest, you sign with an upload key
and Play re-signs. Most Android “RN bugs” are manifest, permission, SDK-level or R8 problems.
Download PDF Print view LaTeX source
Gradle, SDK levels, Play rules
- Three SDK numbers:
minSdk= oldest device that installs;compileSdk= APIs you can call;targetSdk= which new behaviours you opt into. - Play target API: since 31 Aug 2026 new apps and updates must target API 36 (Wear/Automotive 35, TV/XR 34; extension to 1 Nov 2026 on request); existing apps below 35 stop reaching new users on newer Android.
- 16 KB pages: targets Android 15+ must support 16 KB-page 64-bit devices (Android guide: updates blocked from 1 Feb 2027). AGP 8.5.1+/NDK r28+ align by default; RN is compliant since 0.77 — check third-party
.soin APK Analyzer. - Toolchain: JDK 17; AGP comes via RN’s Gradle plugin; 0.87 adds AGP 9 (
android.builtInKotlin=false,android.newDsl=false). Since 0.82newArchEnabled=falseis ignored.
Manifest
- Merged: every library adds its manifest — read Android Studio’s Merged Manifest tab; drop an unwanted permission with
tools:node="remove". android:exportedmust be explicit on any component with an intent filter (Android 12+), else the app won’t install. Launcher activity: true.- Template
MainActivity:singleTask(deep links reuse it),adjustResize,configChanges(rotation keeps the React root). App Links:autoVerify+/.well-known/assetlinks.json.
Example — manifest + permission
<uses-permission android:name="android.permission.CAMERA"/>
<activity android:name=".MainActivity" android:exported="true"
android:launchMode="singleTask"
android:windowSoftInputMode="adjustResize">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW"/>
<category android:name="android.intent.category.DEFAULT"/>
<category android:name="android.intent.category.BROWSABLE"/>
<data android:scheme="https" android:host="example.com"/>
</intent-filter></activity>
<!-- JS: await PermissionsAndroid.request(PERMISSIONS.CAMERA)
'granted' | 'denied' | 'never_ask_again' -> openSettings -->
Runtime permissions
- Dangerous permissions (Android 6+) need manifest and a runtime request: check → rationale (
shouldShowRequestPermissionRationale) → request.POST_NOTIFICATIONSis runtime since Android 13. - Android 11+: Deny twice = “don’t ask again” — the dialog never shows, send users to Settings. “Only this time” for location/camera/mic; unused apps get permissions auto-reset. Re-check on every resume.
Back, edge-to-edge, R8, signing
- BackHandler: listeners run LIFO;
return trueconsumes; none → default back. An openModalblocks BackHandler — useonRequestClose. - Target 36: predictive back on by default,
onBackPressednot called,KEYCODE_BACKnot dispatched (BackHandler still works for most cases; opt-outenableOnBackInvokedCallback="false"); edge-to-edge can’t be opted out — use safe-area insets. - R8 keeps only what it sees: reflection, JNI, JSON-by-field-name need
-keep class …/@Keep. - Signing:
keytool -genkeypair … -validity 10000→ upload key; passwords iñ/.gradle/gradle.properties, not git. Play App Signing holds the real key, so a lost upload key can be reset.
Build errors → fix
- SDK location not found →
ANDROID_HOME/local.properties. Java version errors → JDK 17 (JAVA_HOME). - Duplicate class … in modules → two versions of one library: align/exclude. Incompatible Kotlin metadata → align Kotlin versions.
INSTALL_FAILED_UPDATE_INCOMPATIBLE→ different signing key: uninstall. Unable to load script →adb reverse tcp:8081 tcp:8081.- Release-only
ClassNotFoundException→ keep rules. Stale native build →./gradlew clean, deleteapp/.cxx.
Traps
- The template’s
releaseuses the debug keystore — replace it before shipping. - Bumping
targetSdk“just for Play” — it switches on new behaviour (back, edge-to-edge); test it like a feature.
Remember
min = who installs · compile = what you call · target = how you behave. You sign uploads; Play signs installs.