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

cortinico · 2024-08-20T14:47:26Z

cortinico
Aug 20, 2024
Maintainer

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

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 · 2024-08-20T14:50:27Z

mrousavy
Aug 20, 2024
Collaborator

great work guys!! 👏 🔥

0 replies

Kudo · 2024-08-20T15:27:31Z

Kudo
Aug 20, 2024
Maintainer

super excited for the change 🤩

1 reply

adsalihac Aug 20, 2024

🔥

migueldaipre · 2024-08-20T22:05:10Z

migueldaipre
Aug 20, 2024

Amazing guys 🤯🔥

0 replies

AndreiCalazans · 2024-08-21T11:58:19Z

AndreiCalazans
Aug 21, 2024

This is very clear communication. Thank you.

0 replies

fjmorant · 2024-08-23T11:39:11Z

fjmorant
Aug 23, 2024

exciting 🔥

0 replies

shubhamguptadream11 · 2024-09-06T06:27:19Z

shubhamguptadream11
Sep 6, 2024

Super excited for this🔥

0 replies

fenilkanjanid11 · 2024-09-06T09:41:30Z

fenilkanjanid11
Sep 6, 2024

This is amazing!

0 replies

tomekzaw · 2024-09-16T13:17:47Z

tomekzaw
Sep 16, 2024

~~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.

9 replies

gabrieldonadel Sep 17, 2024
Collaborator

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

cortinico Sep 23, 2024
Maintainer Author

Fix for this is here:

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

ospfranco Oct 26, 2024

Facing this one as well, is the fix published?

cortinico Oct 26, 2024
Maintainer Author

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 Oct 28, 2024

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 · 2024-09-19T03:23:14Z

hushizhi
Sep 19, 2024

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

1 reply

cortinico Sep 19, 2024
Maintainer Author

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

muhammadashfaq · 2024-10-11T10:57:36Z

muhammadashfaq
Oct 11, 2024

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! 💪

0 replies

ospfranco · 2024-10-26T07:58:22Z

ospfranco
Oct 26, 2024

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?

3 replies

cortinico Oct 29, 2024
Maintainer Author

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 Oct 30, 2024
Collaborator

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

cortinico Oct 30, 2024
Maintainer Author

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 · 2024-10-28T15:35:33Z

valery-lavrik
Oct 28, 2024

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.

1 reply

cortinico Oct 29, 2024
Maintainer Author

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 12 comments 15 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

Select a reply

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

cortinico Aug 20, 2024 Maintainer

Context

What’s the impact of this change

What has changed?

How am I affected?

Replies: 12 comments · 15 replies

mrousavy Aug 20, 2024 Collaborator

Kudo Aug 20, 2024 Maintainer

gabrieldonadel Sep 17, 2024 Collaborator

cortinico Sep 23, 2024 Maintainer Author

cortinico Oct 26, 2024 Maintainer Author

cortinico Sep 19, 2024 Maintainer Author

cortinico Oct 29, 2024 Maintainer Author

mrousavy Oct 30, 2024 Collaborator

cortinico Oct 30, 2024 Maintainer Author

cortinico Oct 29, 2024 Maintainer Author

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

cortinico
Aug 20, 2024
Maintainer

Replies: 12 comments 15 replies

mrousavy
Aug 20, 2024
Collaborator

Kudo
Aug 20, 2024
Maintainer

gabrieldonadel Sep 17, 2024
Collaborator

cortinico Sep 23, 2024
Maintainer Author

cortinico Oct 26, 2024
Maintainer Author

cortinico Sep 19, 2024
Maintainer Author

cortinico Oct 29, 2024
Maintainer Author

mrousavy Oct 30, 2024
Collaborator

cortinico Oct 30, 2024
Maintainer Author

cortinico Oct 29, 2024
Maintainer Author