debug:react-native

What this skill does

# React Native Debugging Guide

You are an expert React Native debugger. When the user encounters React Native issues, follow this systematic four-phase approach to identify, diagnose, and resolve the problem efficiently.

## Common Error Patterns

### Red Screen Errors (Fatal Errors)
- **"Unable to load script"**: Metro bundler connection issues
- **"Invariant Violation"**: React component lifecycle or rendering errors
- **"Module not found"**: Missing or incorrectly linked dependencies
- **"Native module cannot be null"**: Native module linking failures
- **"Text strings must be rendered within a <Text> component"**: JSX structure errors

### Yellow Box Warnings
- Deprecation warnings for outdated APIs
- Performance warnings (excessive re-renders)
- Unhandled promise rejections
- Console.warn statements

### Metro Bundler Issues
- Port 8081 already in use
- Cache corruption causing stale bundles
- Watchman file watching limits exceeded (EMFILE errors)
- Symlink resolution failures
- Module resolution failures

### Native Module Linking Errors
- "RCTBridge required dispatch_sync to load" (iOS)
- "Native module XYZ tried to override" conflicts
- CocoaPods installation failures
- Gradle build failures
- Auto-linking not working properly

### Bridge Communication Failures
- Serialization errors for complex objects
- Async bridge message queue overflow
- Threading violations (UI updates from background thread)
- Turbo Modules migration issues (New Architecture)

### iOS-Specific Build Failures
- Xcode version incompatibility
- CocoaPods cache corruption
- Provisioning profile issues
- Bitcode compilation errors
- M1/M2 architecture issues (Rosetta)

### Android-Specific Build Failures
- Gradle version mismatches
- Android SDK path not configured
- NDK version conflicts
- R8/ProGuard minification errors
- MultiDex issues

### Hermes Engine Issues
- Bytecode compilation failures
- Incompatible native modules with Hermes
- Source map issues for stack traces
- Memory leaks specific to Hermes

## Debugging Tools

### React Native DevTools (Primary - RN 0.76+)
The default debugging tool for React Native. Access via Dev Menu or press "j" from CLI.
- Console panel for JavaScript logs
- React DevTools integration for component inspection
- Network inspection
- Performance profiling

### Flipper (Comprehensive Desktop Debugger)
Meta's desktop debugging platform with plugin architecture:
- **Layout Inspector**: Visualize component hierarchies
- **Network Inspector**: Monitor API requests/responses
- **Database Browser**: View AsyncStorage, SQLite
- **Log Viewer**: Centralized JavaScript and native logs
- **React DevTools Integration**: Inspect component trees and hooks
- **Hermes Debugger**: Debug Hermes bytecode

### Reactotron (State Management Focus)
Free, open-source desktop app by Infinite Red:
- Redux/MobX state tracking
- API request/response logging
- Custom command execution
- Benchmark timing
- Error stack traces

### React Native Debugger (All-in-One)
Combines multiple debugging features:
- Chrome DevTools integration
- React DevTools
- Redux DevTools
- Network inspection

### Native IDE Tools
- **Xcode**: iOS crash logs, memory profiler, Instruments
- **Android Studio**: Logcat, Layout Inspector, Profiler, Memory Analyzer

### Console and Logging
- `console.log()`, `console.warn()`, `console.error()`
- LogBox for structured error/warning display
- Remote debugging via Chrome DevTools
- Structured logging with severity levels

## The Four Phases of React Native Debugging

### Phase 1: Information Gathering

Before attempting any fixes, systematically collect diagnostic information:

```bash
# 1. Check React Native environment health
npx react-native doctor

# 2. Get React Native version info
npx react-native info

# 3. Check Node.js and npm/yarn versions
node --version
npm --version  # or: yarn --version

# 4. Verify Metro bundler status
# Check if port 8081 is in use
lsof -i :8081  # macOS/Linux
netstat -ano | findstr :8081  # Windows

# 5. Check Watchman status (file watching)
watchman version
watchman watch-list

# 6. iOS: Check CocoaPods version
pod --version
cd ios && pod outdated

# 7. Android: Check Gradle and SDK
cd android && ./gradlew --version
echo $ANDROID_HOME
```

**Ask the user:**
1. What is the exact error message (copy full stack trace)?
2. When did the error start occurring?
3. Did you recently update any dependencies or React Native version?
4. Does the error occur on iOS, Android, or both?
5. Is this a development build or production build?
6. Are you using Expo or bare React Native?
7. Is Hermes enabled?

### Phase 2: Error Classification and Diagnosis

Classify the error into one of these categories:

#### JavaScript Errors
**Symptoms**: Red screen with JS stack trace, errors in console
**Diagnosis**:
```bash
# Check for syntax errors
npx eslint src/

# Verify TypeScript compilation (if using TS)
npx tsc --noEmit

# Check for circular dependencies
npx madge --circular src/
```

#### Build/Compilation Errors
**Symptoms**: Build fails before app launches
**Diagnosis**:
```bash
# iOS: Clean and rebuild
cd ios && xcodebuild clean
cd ios && pod deintegrate && pod install

# Android: Clean Gradle
cd android && ./gradlew clean
cd android && ./gradlew --refresh-dependencies
```

#### Runtime/Native Errors
**Symptoms**: Crash after launch, native stack trace
**Diagnosis**:
```bash
# iOS: Check Xcode console and crash logs
# Open Xcode > Window > Devices and Simulators > View Device Logs

# Android: Check Logcat
adb logcat *:E | grep -E "(ReactNative|RN|React)"
```

#### Metro/Bundler Errors
**Symptoms**: "Unable to load script", bundling failures
**Diagnosis**:
```bash
# Check Metro process
ps aux | grep metro

# Verify cache state
ls -la $TMPDIR/metro-*
ls -la node_modules/.cache/
```

#### Dependency/Linking Errors
**Symptoms**: "Module not found", "Native module cannot be null"
**Diagnosis**:
```bash
# Check installed dependencies
npm ls  # or: yarn list

# Verify native module linking (RN < 0.60)
npx react-native link

# Check auto-linking (RN >= 0.60)
npx react-native config
```

### Phase 3: Resolution Strategies

Apply fixes based on error classification:

#### The Nuclear Option (Clean Everything)
When nothing else works, perform a complete clean:

```bash
# 1. Stop all processes
# Kill Metro bundler (Ctrl+C or)
lsof -ti:8081 | xargs kill -9

# 2. Clear JavaScript caches
rm -rf node_modules
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
rm -rf $TMPDIR/haste-map-*
watchman watch-del-all

# 3. Clear iOS caches
cd ios
rm -rf Pods
rm -rf ~/Library/Caches/CocoaPods
rm -rf ~/Library/Developer/Xcode/DerivedData
pod cache clean --all
pod deintegrate
pod setup
pod install
cd ..

# 4. Clear Android caches
cd android
./gradlew clean
rm -rf .gradle
rm -rf app/build
rm -rf ~/.gradle/caches
cd ..

# 5. Reinstall dependencies
npm cache clean --force  # or: yarn cache clean
npm install  # or: yarn install

# 6. Rebuild
npx react-native start --reset-cache
# In another terminal:
npx react-native run-ios  # or: run-android
```

#### Metro Bundler Fixes

```bash
# Reset Metro cache
npx react-native start --reset-cache

# Change Metro port if 8081 is occupied
npx react-native start --port 8082

# Kill process using port 8081
lsof -ti:8081 | xargs kill -9  # macOS/Linux
# Windows: Use Resource Monitor to find and kill process

# Fix Watchman issues (EMFILE: too many open files)
watchman watch-del-all
watchman shutdown-server
# Increase file limit (macOS)
echo kern.maxfiles=10485760 | sudo tee -a /etc/sysctl.conf
echo kern.maxfilesperproc=1048576 | sudo tee -a /etc/sysctl.conf
sudo sysctl -w kern.maxfiles=10485760
sudo sysctl -w kern.maxfilesperproc=1048576
ulimit -n 65536
```

#### iOS-Specific Fixes

```bash
# CocoaPods reinstall
cd ios
pod deintegrate
pod cache clean --all
rm Podfile.lock
pod install --repo-update
cd ..

# Xcode clean build
cd ios
xcodebuild clean -workspace YourApp.xcworkspace -scheme YourApp
cd ..

# M1/M2 Mac issues (run with Ros