React Native

---
name: React Native
description: Build performant cross-platform mobile apps with React Native components, navigation, and native modules.
metadata: {"clawdbot":{"emoji":"📱","requires":{"anyBins":["npx","expo"]},"os":["linux","darwin","win32"]}}
---

# React Native Development Rules

## Component Performance
- `FlatList` for any list over 10 items — `ScrollView` with `map` loads everything in memory, FlatList virtualizes
- `keyExtractor` must return stable unique strings — using index causes bugs on reorder and deletion
- `React.memo` prevents re-renders when props unchanged — wrap pure display components
- `useCallback` for functions passed to child components — new function reference triggers child re-render
- Avoid inline styles in render — creates new object every render, extract to `StyleSheet.create`

## State Management
- `useState` is fine for component-local state — don't add Redux/Zustand for a toggle
- Lift state to lowest common ancestor only — higher causes unnecessary re-renders
- `useMemo` for expensive computations — but don't overuse, caching has overhead
- Context re-renders all consumers on any change — split contexts by update frequency
- Avoid storing derived data in state — compute during render from source state

## Navigation
- React Navigation is the standard — Expo Router for file-based routing in Expo projects
- Stack screens stay mounted by default — clean up subscriptions and timers in `useEffect` cleanup
- Pass serializable params only — functions and complex objects break deep linking and state persistence
- `useFocusEffect` for screen-specific side effects — runs on focus, not just mount
- `navigation.reset` for auth flows — clears back stack, prevents returning to login after sign-in

## Styling
- `StyleSheet.create` outside component body — creates styles once, not every render
- Flexbox defaults differ from web — `flexDirection: 'column'`, no `display: flex` needed
- Dimensions in density-independent pixels — don't use pixel values from design tools directly
- `Platform.select` for platform-specific styles — cleaner than conditionals in style objects
- No CSS inheritance — text styles don't cascade, each Text needs explicit styling

## Native Modules
- Expo modules cover most needs — avoid ejecting for common features like camera, location, notifications
- `expo-dev-client` enables native modules without full eject — best of both worlds
- React Native New Architecture (Fabric, TurboModules) is opt-in — check library compatibility before enabling
- Native crashes don't show in JS debugger — check Xcode/Android Studio logs

## Performance Debugging
- Hermes engine should be enabled — significantly faster startup and lower memory
- `InteractionManager.runAfterInteractions` defers heavy work — keeps animations smooth
- `useNativeDriver: true` for animations — runs on UI thread, not JS thread
- `console.log` in production kills performance — remove or use `__DEV__` guard
- Flipper for debugging — network, layout, performance profiling

## Images
- Use `resizeMode` appropriately — `cover` crops, `contain` letterboxes, `stretch` distorts
- Prefetch images for smooth UX: `Image.prefetch(url)` before displaying
- Local images need explicit dimensions — remote images can use aspect ratio if one dimension set
- SVGs via `react-native-svg` — better scaling than PNGs for icons
- Cache remote images with `react-native-fast-image` — default Image has no persistent cache

## Common Mistakes
- `async` in `useEffect` directly — must define async function inside, then call it
- Missing `key` warnings in lists — always use unique, stable keys
- Assuming web React patterns work — no DOM, no CSS, different event system
- Forgetting cleanup in `useEffect` — subscriptions, timers, listeners leak without cleanup return
- Testing only on one platform — iOS and Android differ in behavior, test both regularly

## Platform Differences
- Android needs explicit `overflow: 'hidden'` for border radius clipping — iOS clips by default
- Shadows: iOS uses `shadow*` props, Android uses `elevation`
- StatusBar behavior differs — test visibility and color on both platforms
- Back button is Android-only — handle with `BackHandler` or navigation listeners
- Push notifications setup differs significantly — platform-specific configuration required

## Build & Release
- `npx react-native clean` for unexplained build failures — clears caches and derived data
- iOS: `cd ios && pod install` after adding native dependencies — often forgotten step
- Android: `cd android && ./gradlew clean` for stubborn build issues
- EAS Build (Expo) simplifies CI/CD — handles signing, versioning, submission
- Test release builds locally before submitting — development and production behavior differ