[0.76] Introducing libreactnative.so - Reducing app size and improving startup time on Android

[cortinico]

tl;dr: React Native 0.76 will ship with a reduced number of dynamic libraries: this reduces app size, and improves performance. This is a breaking change if you’ve been writing C++ libraries for Android. This post is for advanced React Native developers. If you’re an app developer, this change will not affect you

React Native 0.76 for Android will ship with a dynamic library called libreactnative.so. This library merges the dynamic libraries we used to ship in previous versions and offers improvements in disk size and performance.

Keep reading to learn more about this change and how you can adapt your Android/C++ libraries to comply with it.

Context

Historically, React Native for Android used to ship a long list of dynamic libraries (aka .so files). This was caused by our folder structure. On top of that, a lot of different libraries had a JNI_OnLoad method that was causing several duplicate symbols.

For example, an Android app with React Native 0.74 ships with 43 dynamic libraries:

 lib/arm64-v8a/libc++_shared.so
 lib/arm64-v8a/libfabricjni.so
 lib/arm64-v8a/libfbjni.so
 lib/arm64-v8a/libfolly_runtime.so
 lib/arm64-v8a/libglog.so
 lib/arm64-v8a/libhermes.so
 lib/arm64-v8a/libhermes_executor.so
 lib/arm64-v8a/libhermesinstancejni.so
 lib/arm64-v8a/libimagepipeline.so
 lib/arm64-v8a/libjscinstance.so
 lib/arm64-v8a/libjsi.so
 lib/arm64-v8a/libjsijniprofiler.so
 lib/arm64-v8a/libjsinspector.so
 lib/arm64-v8a/libmapbufferjni.so
 lib/arm64-v8a/libnative-filters.so
 lib/arm64-v8a/libnative-imagetranscoder.so
 lib/arm64-v8a/libreact_codegen_rncore.so
 lib/arm64-v8a/libreact_cxxreactpackage.so
 lib/arm64-v8a/libreact_debug.so
 lib/arm64-v8a/libreact_devsupportjni.so
 lib/arm64-v8a/libreact_featureflags.so
 lib/arm64-v8a/libreact_featureflagsjni.so
 lib/arm64-v8a/libreact_nativemodule_core.so
 lib/arm64-v8a/libreact_newarchdefaults.so
 lib/arm64-v8a/libreact_render_componentregistry.so
 lib/arm64-v8a/libreact_render_core.so
 lib/arm64-v8a/libreact_render_debug.so
 lib/arm64-v8a/libreact_render_element.so
 lib/arm64-v8a/libreact_render_graphics.so
 lib/arm64-v8a/libreact_render_imagemanager.so
 lib/arm64-v8a/libreact_render_mapbuffer.so
 lib/arm64-v8a/libreact_utils.so
 lib/arm64-v8a/libreactnativeblob.so
 lib/arm64-v8a/libreactnativejni.so
 lib/arm64-v8a/libreactperfloggerjni.so
 lib/arm64-v8a/librninstance.so
 lib/arm64-v8a/librrc_image.so
 lib/arm64-v8a/librrc_legacyviewmanagerinterop.so
 lib/arm64-v8a/librrc_view.so
 lib/arm64-v8a/libruntimeexecutor.so
 lib/arm64-v8a/libturbomodulejsijni.so
 lib/arm64-v8a/libuimanagerjni.so
 lib/arm64-v8a/libyoga.so

In React Native 0.76, the list of dynamic libraries has been reduced to 10:

lib/arm64-v8a/libappmodules.so				# The app code
lib/arm64-v8a/libc++_shared.so				# The c++ shared library
lib/arm64-v8a/libfbjni.so				    # From 3p library: fbjni
lib/arm64-v8a/libhermes.so					# Hermes engine
lib/arm64-v8a/libimagepipeline.so			# From 3p library: fresco
lib/arm64-v8a/libjsi.so						# JSI 
lib/arm64-v8a/libnative-filters.so			# From 3p library: fresco
lib/arm64-v8a/libnative-imagetranscoder.so	# From 3p library: fresco
lib/arm64-v8a/libhermestooling.so			# Hermes engine extra tools
lib/arm64-v8a/libreactnative.so				# React Native core 

This was possible thanks to the introduction of Native Library Merging for React Native Android.

What’s the impact of this change

Native Library Merging is a feature that we use at Meta when shipping all of our Android apps. You can read more about it here: https://engineering.fb.com/2018/01/23/android/android-native-library-merging/

This feature was not available to React Native app users yet, due to limitations of the React Native build and SoLoader. In React Native 0.76, we were able to lift those limitations and ship Native Library Merging for everyone.

You will immediately see benefits in Android app size, with an empty app reducing by ~3.8MB (20%):

This will also benefit app startup time: we need to load fewer libraries, so your app will start faster.

Specifically between 0.75 and 0.76 we noticed a reduction of ~15ms (~8%) at median startup time:

# BEFORE (0.75)

ExampleStartupBenchmark_startup
timeToInitialDisplayMs   min 194.0,   median 201.9,   max 229.5
Traces: Iteration 0 1 2 3 4 5 6 7 8 9

# AFTER (0.76)

ExampleStartupBenchmark_startup
timeToInitialDisplayMs   min 173.3,   median 185.4,   max 206.5
Traces: Iteration 0 1 2 3 4 5 6 7 8 9

_Benchmark methodology: Measures taken on a Pixel Fold (Android 14), averaging 10 runs, using the Android’s default Macro-benchmark test called timeToInitialDisplayMs (source).

This change enables future optimization opportunities such as Link Time Optimization.

What has changed?

We merged a lot of the internal React Native C++ libraries inside a single dynamic library called libreactnative.so. This library is accessible via prefab in your CMakeLists.txt file with the selector ReactAndroid::reactnative and all the headers that were previously available in the other libraries are still available.

We also refactored the other dynamic libraries for JS engines:

• libhermes.so is the Hermes Engine
• libhermestooling.so contains all the tooling needed when running Hermes
• libjsc.so is the JSC Engine
• libjsctooling.so contains all the tooling needed when running JSC

Those libraries are selectively removed from the final APK whether you’re using Hermes or JSC, to save space in the final APK.

The dependency of those dynamic modules looks as follows:

flowchart TB
    libhermestooling.so --> libhermes.so
    libhermes.so --> libjsi.so
    libreactnative.so --> libjsi.so
    libjscstooling.so --> libjsc.so
    libjsc.so --> libjsi.so
    libappmodules.so --> libreactnative.so

Loading

We’re also exposing libjsi.so as a separate dynamic library for advanced users to consume as ReactAndroid::jsi

How am I affected?

This is a breaking change for library users writing C++ code.
If you’re not writing custom C++ code, you won’t be affected by this change at all.

Here's a (non-exhaustive) list of some popular libraries that will need to update. We'll work with them in the coming months to make sure those libraries won’t break in React Native 0.76:

ammarahm-ed/react-native-mmkv-storage
Expensify/react-native-live-markdown
jpudysz/react-native-unistyles
mrousavy/react-native-vision-camera
Shopify/react-native-skia
software-mansion/react-native-gesture-handler
software-mansion/react-native-reanimated

If you’re affected by this change, your Android build will start failing in 0.76 with an error message similar to this one:

[...]

  CMake Error at CMakeLists.txt:34 (add_library):
    Target "mylibrary" links to target "ReactAndroid::react_render_core" but
    the target was not found.  Perhaps a find_package() call is missing for an
    IMPORTED target, or an ALIAS target is missing?

[...]

You can migrate your library already today to support this change in 0.76 (you don't need to wait for the 76 release).

The suggested change needs to be applied in your library’s CMakeLists.txt file and looks like the following.

# Example for a library called `mylibrary` which used to
# link against `react_render_core`, `react_render_uimanager` and `jsi`
# but from 0.76 will just link against `reactnative` and `jsi`

- target_link_libraries(mylibrary 
- 	ReactAndroid::react_render_core 
-   ReactAndroid::react_render_uimanager 
-   ReactAndroid::jsi
- )

+# This if-then-else can be removed once this library does not support version below 0.76
+if (REACTNATIVE_MERGED_SO)
+   target_link_libraries(mylibrary ReactAndroid::reactnative)
+else()
+   target_link_libraries(mylibrary 
+      ReactAndroid::react_render_core 
+      ReactAndroid::react_render_uimanager
+   )
+endif()
+target_link_libraries(mylibrary ReactAndroid::jsi)

[mrousavy]

great work guys!! 👏 🔥

[Kudo]

super excited for the change 🤩

[adsalihac]

🔥

[migueldaipre]

Amazing guys 🤯🔥

[AndreiCalazans]

This is very clear communication. Thank you.

[fjmorant]

exciting 🔥

[shubhamguptadream11]

Super excited for this🔥

[fenilkanjanid11]

This is amazing!

[tomekzaw]

Heads-up: REACTNATIVE_MERGED_SO is not defined (perhaps you should define it yourself).

Instead, we're using if (ReactAndroid_VERSION_MINOR GREATER_EQUAL 76) check.

[gabrieldonadel]

Yeah I'm facing the same issues described by @tomekzaw in Expo Libraries

[cortinico]

Fix for this is here:

• Properly set REACTNATIVE_MERGED_SO for autolinked libraries. facebook/react-native#46606

[ospfranco]

Facing this one as well, is the fix published?

[cortinico]

Yes fix is included in 0.76.0

Which library are you experiencing this with? Could you create a small repro so I could take a look @ospfranco ?

[kraenhansen]

We're experiencing the same with realm (we were too slow in adopting the RCs for the 0.76 release 🙄) - also please let me know if I should create a new thread or issue to track this.

Our CMakeList.txt is driven by an externalNativeBuild in our library's build.gradle, so not a "pure C++" turbo module, but still technically "autolinked".

[hushizhi]

Great. In an old project that uses android.mk to build SO files, is there a similar feature available for merging SO files?

[cortinico]

Nope, So Merging is implemented only for CMake and not for Android.mk files

[muhammadashfaq]

Super excited for this! 🎉 The way you guys are making progress, by the time you hit 1.0 🚀, it’s going to be so much more stable! 💪

[ospfranco]

Where can I find the namespaces names of the exposed ReactAndroid::libs?

I depend on:

  fbjni::fbjni
  ReactAndroid::jsi
  ReactAndroid::turbomodulejsijni
  ReactAndroid::react_nativemodule_core
  android

But it's not clear to me with what should I replace them?

[cortinico]

You'll have to depend on:

  fbjni::fbjni                // Not owned by us - that's fbjni
  ReactAndroid::reactnative   // Owned by us - that's libreactnative.so
  android                     // Not owned by us - that's android

[mrousavy]

ReactAndroid::jsi is still separate from ReactAndroid::reactnative though, right?

[cortinico]

You're right, I overlooked. The correct response is:

  fbjni::fbjni                // Not owned by us - that's fbjni
  ReactAndroid::jsi           // Owned by us - that's libjsi.so
  ReactAndroid::reactnative   // Owned by us - that's libreactnative.so
  android                     // Not owned by us - that's android

[valery-lavrik]

I don't understand anything. I updated my application from 0.74.0 version to 0.76.0 and my application began to weigh 2 times more (it was 35mb, it became 79 mb) What went wrong, I don't understand.

The old version - https://disk.yandex.ru/d/YpF1K_DXu1BstA
New version - https://disk.yandex.ru/d/DBgH6SauAP16ZQ

Maybe they'll tell me what's the matter here? I just updated react-native and that's it.

[cortinico]

See my answer here:

• after upgrading to version 0.76.0, the application began to weigh 2 times more facebook/react-native#47222 (comment)

Tl;dr: you're bumping 2 versions of RN and this is unrelated to libreactnative.so

[Feng999]

Can I use this feature in old React Native version? such as 0.72.5?

[cortinico]

Nope this requires React Native 0.76+