react native - Guide - ITSupportWale

Table of Contents

React Native: The Bridge is a Bottleneck and Your Build Pipeline is a Lie

It was 3:14 AM on a Tuesday in 2021. I was staring at a Grafana dashboard that looked like a heart attack. Our flagship app, built on react native 0.63 at the time, was crashing for 40% of users on Android. The error? java.lang.RuntimeException: ReadableNativeMap.java:115. No stack trace. No context. Just a cryptic OOM (Out of Memory) error that only triggered when users tried to checkout using our Stripe integration. We had pushed a “minor” UI update that inadvertently triggered a re-render loop in a FlatList, which in turn flooded the Bridge with 50MB of JSON data every second. The Bridge didn’t just slow down; it choked, backed up the message queue, and the Android OS OOM-killed the process to save the kernel.

I spent eighteen hours bisecting commits and digging through node_modules to find a single useEffect hook that lacked a dependency array. That’s the reality of React Native. It’s not “Write Once, Run Anywhere.” It’s “Write Once, Debug Everywhere until you want to throw your MacBook Pro into a woodchipper.” If you’re here for a tutorial on how to make a Todo list, go to the official docs. If you want to know why your production app is dropping frames and why your CI/CD pipeline takes 45 minutes to fail, keep reading.

The Documentation is Lying to You

The official React Native documentation is written for people living in a vacuum. It assumes you have a clean environment, a single version of Ruby, and that npx react-native init works on the first try. It doesn’t. In the real world, you’re dealing with rbenv, nvm, cocoapods version mismatches, and the specific brand of YAML-hell that comes with bitrise.yml or GitHub Actions.

The biggest lie is that you don’t need to know native code. To run a serious React Native app, you need to be a Senior Android Engineer, a Senior iOS Engineer, and a Senior Web Engineer simultaneously. When the build fails with Duplicate class com.google.common.util.concurrent.ListenableFuture, your knowledge of React hooks is worthless. You need to know how to navigate build.gradle and exclude transitive dependencies. React Native is an abstraction layer, and all abstractions are leaky. This one leaks like a sieve.

The Threading Model: Where Performance Goes to Die

To understand why your app stutters, you have to understand the three main threads in React Native (pre-New Architecture):

The JS Thread: Where your business logic lives. If you do a heavy Array.map() here, your UI freezes.
The UI Thread (Main Thread): Where the actual native views (UIView, Android.View) are manipulated.
The Shadow Thread: Where Yoga (the layout engine) calculates positions before sending them to the UI thread.

The problem is the Bridge. Every time you want to update a view, the JS thread serializes a JSON message, sends it over the Bridge, the Shadow thread calculates the layout, and the UI thread renders it. This is asynchronous. If you’re trying to sync a gesture (like a swipe) with an animation, the round-trip latency across the Bridge creates that “uncanny valley” feeling where the UI feels sluggish.

Pro-tip: If you are still using the “Old Architecture,” stop doing heavy calculations in render(). Use useMemo religiously, but more importantly, offload animations to the native thread using useNativeDriver: true. If you don’t, you’re just burning battery for fun.

The “New Architecture” and the JSI

React Native is currently in a transition period. Version 0.74+ is pushing the “New Architecture” hard. They’ve replaced the Bridge with the JSI (JavaScript Interface). Instead of serializing JSON, the JS engine (Hermes) now has a direct reference to C++ host objects. This is supposed to be the “savior” of the framework.

Is it better? Yes. Is it a headache? Absolutely. Enabling the New Architecture (Fabric for UI, TurboModules for native logic) requires you to rewrite your native modules in C++. If you thought finding a good Swift developer was hard, try finding a React Native developer who is comfortable with C++ memory management.


// Example of a TurboModule spec in TypeScript
// This is what the New Architecture expects. No more 'NativeModules.MyModule'
import { TurboModule, TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  readonly getDeviceName: () => string;
  readonly triggerHeavyCalculation: (input: number) => Promise<string>;
}

export default TurboModuleRegistry.getEnforced<Spec>('MyCustomModule');

The JSI allows for synchronous execution. This means you can finally have a synchronous call to a native database (like Realm or SQLite) without the 100ms Bridge overhead. But it also means if your native code blocks, your JS thread dies. We’ve traded one bottleneck for a different kind of responsibility.

The Build Pipeline: A Comedy of Errors

Let’s talk about pod install. In a 10-person team, someone will eventually update their macOS, which updates Ruby, which breaks ffi, which breaks CocoaPods. Suddenly, the entire team is blocked because Hermes-engine won’t compile for arm64 simulators.

In my experience, 40% of an SRE’s time on a React Native project is spent fixing the CI. Here is a typical failure pattern in a config.yml for CircleCI:

Node version mismatch between local and CI (Use .nvmrc, people!).
Android SDK licenses not accepted on the runner.
The node_modules cache is poisoned because someone added a dependency via npm instead of yarn (or vice versa).
iOS code signing certificates expired (Fastlane match is the only sane way to handle this).
The runner runs out of disk space because the ios/build folder is 12GB.
Metro bundler hangs because it found a duplicate Haste module map.

To survive this, you need a strict lockfile policy. If a PR changes yarn.lock and package-lock.json simultaneously, reject it. If a PR adds a native dependency without a corresponding podfile.lock update, reject it. The build must be deterministic, or you will spend your Fridays debugging ld: library not found for -lDoubleConversion.

Memory Leaks: The Silent Killer

Web developers think that because JS has a garbage collector, they don’t need to worry about memory. In React Native, this is a dangerous assumption. When you create a native view (like a MapView or a Video component), the JS object is just a handle. If you unmount the component but the native side doesn’t release the resource, you have a leak.

I once saw an app’s memory usage climb from 200MB to 1.5GB in ten minutes. The culprit? An event listener on the DeviceEventEmitter that wasn’t removed in componentWillUnmount. Every time the user navigated to the “Settings” screen, a new listener was created. The JS objects were small, but they were holding onto large native context objects.


// The "I'm going to crash your app" pattern
useEffect(() => {
  const subscription = DeviceEventEmitter.addListener('onDataReceived', (data) => {
    setGlobalState(data);
  });
  // Missing: return () => subscription.remove();
}, []);

To debug this, you can’t just use the Chrome DevTools. You need Xcode Instruments (specifically the “Allocations” and “Leaks” templates) and Android Studio Profiler. You have to look at the “Native Heap” vs. the “JS Heap.” If the Native Heap is growing while the JS Heap is flat, your problem is in the Bridge or a Native Module.

The “Gotcha” with FlatLists and Images

If you have a list of 500 items and each item has a 2MB image, React Native will try to render them all if you aren’t careful. Unlike a web browser, which is quite good at handling large DOMs, React Native’s FlatList is a complex beast that tries to virtualize rendering.

The problem: windowSize. The default windowSize is 21 (10 screens up, 10 screens down). If your list items are complex, React Native is keeping 21 screens worth of native views in memory. On a low-end Android device with 2GB of RAM, this is a death sentence.

Note to self: Always set removeClippedSubviews={true} on Android. It’s buggy on iOS sometimes, but on Android, it’s the only thing keeping your FlatList from eating the entire heap. Also, use initialNumToRender and maxToRenderPerBatch to throttle the Bridge.

And for the love of all that is holy, use a library like react-native-fast-image. The default Image component in React Native is trash. It doesn’t handle caching well, and it doesn’t prioritize downloads. FastImage wraps SDWebImage (iOS) and Glide (Android), which are the industry standards for a reason.

CodePush: The SRE’s Best Friend and Worst Enemy

Microsoft’s CodePush allows you to push JS updates directly to users, bypassing the App Store and Play Store review process. This is incredible for fixing a critical bug in 10 minutes. It’s also a great way to bypass QA and break your app for everyone.

The danger with CodePush is Native Dependency Mismatch. If your JS code expects a new version of a native module (e.g., you added react-native-reanimated), but the user is running an old binary that doesn’t have that native code, the app will crash on launch. CodePush does not update the native binary. It only updates the index.bundle.

We solved this by implementing a strict versioning contract. Every CodePush release is tied to a specific nativeBuildNumber. If the binary version doesn’t match the bundle’s target version, the update is ignored. It sounds simple, but I’ve seen teams lose weeks of work because they “CodePushed” a change that required a pod install.

The Dependency Hell of React Native

In a standard Node.js project, a dependency is just some JS code. In React Native, a dependency is often a wrapper around a CocoaPod and a Gradle module. This means you are at the mercy of the maintainer’s knowledge of three different ecosystems.

Take react-native-firebase. It’s a fantastic library, but it’s also a massive dependency. When Google updates the Firebase Android SDK, react-native-firebase has to update. If they don’t, you might find yourself unable to build for Android because of a minSdkVersion conflict. You end up in a situation where you can’t update Library A because it depends on an old version of Library B, but Library C requires a new version of Library B.

The solution? Patch-package. If you aren’t using patch-package, you aren’t doing React Native in production. You will inevitably find a bug in a library’s .podspec file or a .java file that the maintainer hasn’t fixed yet. Instead of forking the repo and dealing with the overhead of maintaining a fork, you patch it locally and commit the patch.


// Example: patching a broken build.gradle in a third-party library
// patches/react-native-some-library+1.2.3.patch
--- a/node_modules/react-native-some-library/android/build.gradle
+++ b/node_modules/react-native-some-library/android/build.gradle
@@ -10,7 +10,7 @@
     compileSdkVersion 34 // Manually bumped because the maintainer is MIA

The Performance Profiling Workflow

When someone says “the app is slow,” you need data. Don’t guess. Use the following workflow:

Enable the Perf Monitor: Look at the JS and UI frame rates. If UI is 60fps but JS is 10fps, you have a heavy JS calculation. If JS is 60fps but UI is 10fps, you have too many native views or off-screen rendering issues.
Flipper (Legacy but useful): Use the “React DevTools” to find unnecessary re-renders. Use the “Network” tab to see if you’re fetching 10MB of data when you only need 10KB.
Hermes Debugger: Since RN 0.70, Hermes is the default. Use the chrome://inspect tool to profile the JS heap specifically for Hermes.
Systrace: This is the nuclear option. It gives you a breakdown of exactly what the CPU is doing across all threads. It will show you if the “Ganesh” (Android’s rendering engine) is struggling with a specific layer.

One specific issue we found was “Overdraw.” On Android, if you have a background color on your View, and that View is inside another View with a background color, the GPU has to paint those pixels twice. In a complex screen, you might be painting the same pixel 5 or 6 times. This kills performance on mid-range devices. The fix? Remove unnecessary backgrounds and use collapsable={true} on Android views.

The Monorepo Nightmare

If you’re running React Native in a monorepo (using Nx or Turborepo), God help you. Metro, the React Native bundler, does not like symbolic links. It has improved recently, but for years, you had to use a custom metro.config.js just to make it see code in packages/common.


const path = require('path');
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const workspaceRoot = path.resolve(__dirname, '../..');
const projectRoot = __dirname;

const config = {
  watchFolders: [workspaceRoot],
  resolver: {
    nodeModulesPaths: [
      path.resolve(projectRoot, 'node_modules'),
      path.resolve(workspaceRoot, 'node_modules'),
    ],
    disableHierarchicalLookup: true,
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

Even with this, you’ll run into issues where react-native is hoisted to the root node_modules, but the native build scripts expect it to be in the local node_modules. You’ll end up writing “nohoist” rules in your package.json and praying to the NPM gods.

The Reality of “Cross-Platform”

You will eventually write native code. Whether it’s a custom IntentFilter on Android to handle deep linking or a UNUserNotificationCenterDelegate on iOS for push notifications, you cannot escape the native platforms. The dream of a pure-JS mobile app is only possible for the simplest of CRUD apps.

The real value of React Native isn’t that you only write JS. It’s that you can share the business logic. Your API client, your state management (Redux, Zustand, whatever), and your validation logic can be shared. But your UI layer will always have platform-specific tweaks. If you try to make the Android app look exactly like the iOS app, you will frustrate your users. Android users want a back button; iOS users want a swipe-back gesture. React Native makes it easy to handle both, but you have to actually do the work.

Security: It’s Not a Web Browser

I’ve seen too many developers store API keys in their app.json or .env files. In a web app, you can hide secrets behind a backend. In a mobile app, anything in your JS bundle is public. If I download your APK, I can run strings index.android.bundle | grep "sk_live_" and find your Stripe secret key in five seconds.

Use Keychain on iOS and Keystore on Android. Use libraries like react-native-keychain to store sensitive data. Never, ever store a JWT or a private key in AsyncStorage. AsyncStorage is just a plain-text file on the disk. On a rooted Android device, it’s trivial to read.

The Future: Is it still worth it?

With the rise of Flutter and the improvements in Native (SwiftUI and Jetpack Compose), people keep asking if React Native is dead. It’s not. The ecosystem is too big. The ability to “Over-the-Air” update your app is too powerful for businesses to ignore. But the “hype” phase is over. We are now in the “maintenance and maturity” phase.

React Native is a tool for managing complexity. It allows a smaller team to ship to two platforms, but it requires that team to be more technically diverse. If you treat it like a web framework, it will punish you. If you treat it like a sophisticated C++/Native/JS hybrid, you can build world-class apps.

Final Advice

Stop looking for the “best” navigation library; just use react-navigation. Stop trying to optimize your JS code until you’ve checked your image sizes and Bridge traffic. And for the love of your sanity, keep your native dependencies to a minimum. Every library you add is a potential build failure waiting to happen during your next release cycle. If you can write it yourself in 50 lines of Swift or Kotlin, do it. You’ll thank yourself when the next version of React Native drops and your app actually compiles.

React Native is a powerful, frustrating, brilliant, and broken mess. It’s the best tool we have for cross-platform development, but only if you respect the platforms it’s running on. Now go delete your node_modules and try building again. You know you have to.

Explore more insights and best practices:

react native – Guide