Debugging React Native Android apk on Physical Device

debugging.md

Debugging a React Native app from an APK running on a physical Android device is slightly different from debugging in development mode (npx react-native run-android). Once you build a release APK, it's optimized, minified, and doesn't have debugging tools attached by default. Here's a structured approach depending on whether you're using a debug build APK or a release build APK.

---

🛠️ Option 1: Debug Build APK (recommended for debugging)

If you built a debug APK (debug.apk), debugging is easy:

✅ Steps:

1. Enable Developer Options and USB Debugging on your device.

2. Connect the physical device via USB.

3. Install the debug APK:

   adb install app-debug.apk

4. Open the app on your phone.

5. Shake the device (or press Ctrl + M or Cmd + M on emulator) to open the Developer Menu.

6. Choose "Debug JS Remotely":

   • It opens Chrome DevTools where you can debug console logs, inspect network requests, set breakpoints, etc.

7. Alternatively, use:

   adb logcat *:S ReactNative:V ReactNativeJS:V

   to see logs from React Native and JS side.

---

🔒 Option 2: Release Build APK (debugging is limited)

Release APKs are minified, obfuscated, and don't support Dev Menu. So you must use other tools:

✅ Steps:

1. Enable Native Logging via adb logcat

• Run this in terminal:

  adb logcat *:S ReactNative:V ReactNativeJS:V

• Add console.log, console.error in JS files to see output here.

2. Enable Custom Logging

Use libraries like react-native-logs to save and view logs easily even in release mode.

3. Use Flipper (optional)

If your app is built with Flipper enabled, you can use it in release too (though not common due to bundle size). To enable Flipper in release:

• Modify android/app/proguard-rules.pro to keep Flipper classes
• Be aware: This is not recommended for production

4. Enable Crash Reporting

Use tools like:

• Sentry
• Firebase Crashlytics

They can collect JS and native crashes and stack traces even in release builds.

5. Remote JS Debugging via Console Logs

If you bundle JS manually and inject debug logs:

react-native bundle --platform android --dev true --entry-file index.js --bundle-output index.android.bundle

You can enable better JS logging even in non-debug builds.

---

🚀 Tip: Always build with source maps for release

To debug release issues meaningfully (e.g. in Sentry or Flipper):

react-native bundle \
  --platform android \
  --dev false \
  --entry-file index.js \
  --bundle-output index.android.bundle \
  --sourcemap-output index.android.bundle.map

Upload the .map file to your error tracking tool.

---

📌 Summary

Scenario	Tools/Methods
Debug APK	Dev Menu, Chrome DevTools, adb logcat
Release APK	adb logcat, Crashlytics, Sentry, custom logs
Network Issues	Use proxy tools like Charles, mitmproxy
Native Crashes	Android Studio Profiler, adb logcat, Crashlytics
JS Crashes	Console logs + Sentry with source maps

---

Let me know if you want a setup guide for any of these tools (like Sentry or Crashlytics), or if you want to debug using Flipper or Hermes.