Android 16 KB Page Size Support

Summary

This document captures the Android build changes added to support devices that use a 16 KB memory page size. The changes are limited to Android native build and packaging configuration. No JavaScript, API, navigation, Redux, or screen-level behavior was changed.

16 KB page-size support is required because newer Android devices may use 16 KB memory pages instead of the older 4 KB page size. Native .so libraries must be built and packaged in a compatible way to avoid install issues, startup crashes, or native library loading failures.

Files and Changes

android/build.gradle

The root Android build configuration now standardizes the native toolchain:

buildToolsVersion = "35.0.0"
compileSdkVersion = 35
targetSdkVersion = 35
ndkVersion = "27.1.12297006"
kotlinVersion = "2.0.21"

Purpose:

• Uses NDK 27.1.12297006, which is required for modern Android native builds and 16 KB page-size compatibility.
• Keeps compile and target SDK aligned to Android SDK 35.
• Exposes the same NDK version to the app module through rootProject.ext.ndkVersion.

android/gradle.properties

16 KB page-size support is enabled at the Gradle property level:

android.ndkVersion=27.1.12297006
android.supports16kPages=true
android.native.disableLegacyPageSize=true

Purpose:

• Pins the expected NDK version.
• Enables 16 KB page-size support.
• Disables legacy native page-size behavior.

Related build properties:

reactNativeArchitectures=armeabi-v7a,arm64-v8a
newArchEnabled=true
hermesEnabled=true
android.native.buildOutput=verbose

Purpose:

• Builds the production mobile ABIs used by React Native.
• Keeps Hermes and React Native New Architecture enabled.
• Enables verbose native build output for troubleshooting.

android/app/build.gradle

The app module consumes the root NDK version and applies native packaging changes:

android {
    ndkVersion rootProject.ext.ndkVersion

    defaultConfig {
        externalNativeBuild {
            cmake {
                cppFlags "-DANDROID_SUPPORTS_16K_PAGES=1"
            }
        }

        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }

    packaging {
        jniLibs {
            useLegacyPackaging false
        }
    }
}

Purpose:

• Uses the same NDK version as the root project.
• Adds a native compile flag for 16 KB page-size-aware native builds.
• Restricts native builds to supported production ABIs.
• Disables legacy JNI library packaging.

ABI split output remains enabled:

splits {
    abi {
        reset()
        enable true
        universalApk true
        include "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
    }
}

Purpose:

• Produces ABI-specific APKs.
• Keeps a universal APK available for testing or distribution workflows.
• Includes emulator ABIs for development and validation.

Build Baseline

Item	Value
React Native	0.78.0
React	19.0.0
Gradle wrapper	8.12
Compile SDK	35
Target SDK	35
Min SDK	24
NDK	27.1.12297006
Hermes	Enabled
React Native New Architecture	Enabled

Validation

Build release artifacts:

cd android
./gradlew clean
./gradlew assembleRelease
./gradlew bundleRelease

Check APK alignment:

zipalign -c -P 16 -v 4 app/build/outputs/apk/release/app-release.apk

Verify signing:

apksigner verify --verbose app/build/outputs/apk/release/app-release.apk

Check device page size:

adb shell getconf PAGE_SIZE

Expected value on a 16 KB page-size device:

16384

Runtime validation should include app launch, login, camera, audio recording, document/image picker, WebView, Firebase messaging, MMKV, and file access. Monitor adb logcat for native loading errors such as dlopen failed.

CI Requirements

CI or local release machines should provide:

• JDK 17
• Android SDK Platform 35
• Android Build Tools 35.0.0
• Android NDK 27.1.12297006
• Gradle wrapper from android/gradle/wrapper/gradle-wrapper.properties

Required Android SDK components:

platforms;android-35
build-tools;35.0.0
ndk;27.1.12297006

Future Dependency Notes

When adding or upgrading native React Native dependencies:

• Confirm Android 15+ and 16 KB page-size compatibility.
• Avoid old prebuilt .so files unless verified.
• Rebuild release APK/AAB artifacts.
• Re-run alignment, signing, and runtime checks on a 16 KB page-size device.