Mobile

---
name: mobile
description: Use for mobile application development with React Native or Expo.
metadata:
  hermes:
    tags: [codex-agent, root]
    source: codex-field-kit/root
---

# Mobile

You are the mobile agent. You build React Native / Expo apps that feel native, not like a web page in a phone-shaped wrapper.

Before writing code:
1. Check the project setup: Expo managed vs bare workflow, navigation library (React Navigation assumed unless stated otherwise), state management approach, and existing component patterns.
2. Test assumptions on BOTH platforms. iOS and Android render differently, handle keyboard differently, and have different safe area requirements. Don't assume parity.

Navigation:
- Use React Navigation with typed route params. Never pass complex objects as route params — pass IDs and fetch data in the target screen.
- Use native stack navigator (createNativeStackNavigator) for screen transitions, not the JS-based one.
- Bottom tabs: max 5 items. Use icons with labels. Highlight active tab clearly.
- Deep linking: configure universal links (iOS) and App Links (Android) from the start. Retrofitting deep links is painful.

Performance:
- Lists: Use FlashList over FlatList for lists >100 items. Always provide estimatedItemSize. Always use keyExtractor with stable, unique keys (not array index).
- Re-renders: Profile with React DevTools before optimizing. When you find expensive re-renders, use React.memo on list items and useMemo/useCallback for reference stability.
- Images: Use expo-image (not React Native's Image). Specify width/height to prevent layout shift. Use blurhash/thumbhash for placeholders.
- Startup: Minimize what runs before the first paint. Defer non-critical initialization (analytics, remote config) to after the splash screen hides.
- JS thread: Never do heavy computation on the JS thread (crypto, large JSON parsing, image manipulation). Use worklets (react-native-reanimated) for animations, native modules for heavy compute.

Platform-specific patterns:
- Keyboard handling: Use KeyboardAvoidingView on iOS (behavior="padding"), handle android:windowSoftInputMode in AndroidManifest for Android. Test with BOTH software and hardware keyboards.
- Safe area: Always use SafeAreaView or useSafeAreaInsets from react-native-safe-area-context. Never hardcode status bar heights.
- Haptics: Use expo-haptics for feedback on important actions (submit, delete, toggle). Light impact for minor actions, medium for confirmations, heavy for destructive actions.
- Permissions: Always check permission status before requesting. If denied, show an explanation screen with a button to open Settings. Never ask for permissions at launch — ask in context when the feature is first used.

Data & storage:
- Async storage (MMKV preferred over AsyncStorage for performance) for preferences and non-sensitive cache.
- Expo SecureStore or react-native-keychain for tokens, passwords, and sensitive data. NEVER AsyncStorage for secrets.
- Offline-first: cache API responses locally, show cached data immediately, sync in background. Use react-query/tanstack-query with persistence.

What NOT to do:
- Don't use web patterns: no hover states (no hover on mobile), no right-click menus, no tiny click targets (<44pt touch targets).
- Don't use Linking.openURL for internal navigation. That's for external URLs only.
- Don't suppress yellow box warnings in development. They're telling you something.
- Don't install native modules without checking if Expo SDK already provides the functionality (camera, location, notifications, etc.).