agents-inc/mobile-framework-react-native

React Native Development Patterns

Quick Guide: Build cross-platform mobile apps with React Native's New Architecture (default since 0.76). Use FlashList for performant lists (or FlatList with proper optimization). Use type-safe navigation hooks with static or dynamic API. Keep components small, memoize callbacks passed to lists, and test on both platforms from day one.

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use FlashList (preferred) or FlatList for lists with more than 20 items - NEVER ScrollView with .map() for long lists)

(You MUST memoize renderItem callbacks and use stable keyExtractor functions - avoid key props on FlashList items as it breaks recycling)

(You MUST use react-native-safe-area-context for safe areas - React Native's built-in SafeAreaView is deprecated in 0.81+ and will be removed)

(You MUST test on BOTH iOS AND Android from day one - platform differences cause bugs)

(You MUST use Platform.select() or platform-specific files for platform differences - shadows, fonts, and feedback differ)

(You MUST be aware the New Architecture is enabled by default since React Native 0.76 - Fabric, TurboModules, and bridgeless mode)

</critical_requirements>

---

Auto-detection: React Native, react-native, React Navigation, @react-navigation, StyleSheet, FlatList, FlashList, ScrollView, View, Text, Pressable, TouchableOpacity, Platform.OS, Platform.select, SafeAreaView, KeyboardAvoidingView, Reanimated, Gesture Handler, TurboModules, Fabric, JSI, New Architecture

When to use:

• Building cross-platform iOS and Android mobile applications
• Creating native mobile UIs with React patterns
• Implementing mobile navigation with stack, tab, or drawer patterns
• Optimizing list performance with FlashList/FlatList and virtualization
• Adding gestures and animations with Reanimated 4
• Handling platform-specific code for iOS vs Android differences
• Working with React Native's New Architecture (Fabric, TurboModules, JSI)

Key patterns covered:

• New Architecture fundamentals (Fabric, TurboModules, JSI, bridgeless mode)
• Component architecture with accessibility props and platform-specific patterns
• React Navigation 7+ with type-safe hooks, static API, and auth flows
• FlashList/FlatList optimization with memoization and cell recycling
• Platform-specific code with Platform.select and file extensions
• Safe area and keyboard handling
• React 19 features (React Native 0.78+): useOptimistic, use, ref as props

When NOT to use:

• Web-only React applications (use standard React patterns)
• React Native Web hybrid apps (requires additional considerations)
• Flutter, Swift, or Kotlin native development

Detailed Resources:

• examples/core.md - Component architecture, compound components
• examples/navigation.md - Type-safe navigation, auth flows, deep linking
• examples/styling.md - StyleSheet, design tokens, theming, responsive styling
• examples/performance.md - FlashList, FlatList optimization, memoization
• reference.md - Decision frameworks, checklists, CLI commands

---

<philosophy>

Philosophy

React Native enables building native mobile apps using React patterns. The key insight is that mobile has different constraints than web: performance matters more, platform conventions differ, and users expect native feel.

Core principles:

1. New Architecture first - React Native 0.76+ uses the New Architecture by default (Fabric, TurboModules, JSI, bridgeless mode)
2. Platform-first thinking - iOS and Android have different UX conventions (haptics, ripples, navigation patterns)
3. Performance by default - Mobile devices are constrained; use FlashList/FlatList, memoize callbacks, avoid inline styles
4. Native feel matters - Use native components, proper keyboard handling, safe area insets
5. Type safety prevents bugs - Type navigation params, props, and native module interfaces
6. Test both platforms early - Platform bugs compound over time; test daily on both

New Architecture (React Native 0.76+):

The New Architecture removes the legacy bridge and provides:

• Fabric - Modern rendering engine with synchronous layout effects
• TurboModules - Lazy-loaded native modules with type-safe interfaces
• JSI (JavaScript Interface) - Direct synchronous JS-to-native calls without serialization
• Bridgeless Mode - Complete removal of the async bridge for better performance

Performance improvements with New Architecture: ~15ms faster app startup (~8% improvement), ~3.8MB smaller app size (20% reduction), ~15x faster Metro resolver, ~4x faster warm builds.

Mental model:

React Native is NOT "write once, run anywhere" - it's "learn once, write anywhere." Expect to write some platform-specific code. The shared codebase is typically 80-95%, not 100%.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Component Architecture

Build components with TypeScript, accessibility props, and platform awareness. Key concerns: use Pressable over TouchableOpacity, include accessibilityRole/accessibilityState, use testID for E2E tests, and memoize styles with useMemo.

// Key pattern: accessibility + testID + memoized styles
<Pressable
  ref={ref}
  style={buttonStyle}
  onPress={handlePress}
  disabled={disabled}
  testID={testID}
  accessibilityRole="button"
  accessibilityState={{ disabled }}
>
  <Text style={styles.text}>{children}</Text>
</Pressable>

Why good: accessibilityRole/State for screen readers, testID for E2E, Pressable supports android_ripple unlike TouchableOpacity

See examples/core.md for full component with forwardRef, variants, and loading state.

---

Pattern 2: Safe Area and Keyboard Handling

Handle device notches, status bars, and keyboard properly. Use react-native-safe-area-context (RN's built-in SafeAreaView is deprecated in 0.81+).

import { SafeAreaView, useSafeAreaInsets } from "react-native-safe-area-context";

// Screen wrapper with safe areas
<SafeAreaView style={{ flex: 1 }} edges={["top", "bottom"]}>
  {children}
</SafeAreaView>

// Keyboard handling for forms
<KeyboardAvoidingView
  style={{ flex: 1 }}
  behavior={Platform.OS === "ios" ? "padding" : "height"}
  keyboardVerticalOffset={Platform.select({ ios: HEADER_HEIGHT, android: 0 })}
>
  <ScrollView keyboardShouldPersistTaps="handled">
    <FormContent />
  </ScrollView>
</KeyboardAvoidingView>

Why good: SafeAreaView handles notches/Dynamic Island, KeyboardAvoidingView prevents keyboard overlap, Platform.select handles iOS/Android differences

---

Pattern 3: Platform-Specific Code

Handle iOS and Android differences with Platform.select for small differences, separate files (.ios.tsx/.android.tsx) for significant divergence.

// Platform.select for shadows (iOS shadow props ignored on Android)
const styles = StyleSheet.create({
  card: {
    ...Platform.select({
      ios: {
        shadowColor: "#000",
        shadowOffset: { width: 0, height: 2 },
        shadowOpacity: 0.1,
        shadowRadius: 4,
      },
      android: { elevation: 4 },
    }),
  },
  text: {
    fontWeight: Platform.select({ ios: "600", android: "bold" }),
  },
});

Why good: iOS shadow props are completely ignored on Android, fontWeight 100-900 unreliable on Android

For platform-specific file splitting with haptics, see examples/core.md.

---

Pattern 4: FlashList and FlatList Optimization

Use FlashList for performant lists (cell recycling, 50% less blank area). FlashList v2 is New Architecture only. Always memoize renderItem and keyExtractor. Never add key props to FlashList items (breaks recycling).

// Critical: memoized renderItem + no key prop on items
const renderItem = useCallback(
  ({ item }: { item: Product }) => (
    <ProductItem item={item} onPress={onProductPress} />
  ),
  [onProductPress]
);

<FlashList
  data={products}
  renderItem={renderItem}
  estimatedItemSize={ITEM_HEIGHT} // Optional in v2, required in v1
  getItemType={(item) => item.category} // Improves recycling pool
/>

Why good: useCallback prevents renderItem recreation, getItemType optimizes recycling, no key prop preserves FlashList's main benefit

See examples/performance.md for full FlashList and FlatList optimization patterns.

---

Pattern 5: React 19 Features (React Native 0.78+)

React Native 0.78+ includes React 19 with new hooks and simplified patterns.

import { useOptimistic } from "react";

// useOptimistic - optimistic UI updates with automatic rollback
const [optimisticMessages, addOptimisticMessage] = useOptimistic(
  messages,
  (state, newMessage: Message) => [...state, { ...newMessage, sending: true }]
);

// ref as props - no more forwardRef wrapper needed (React 19)
function Input({ ref, placeholder, onChangeText }: InputProps) {
  return <TextInput ref={ref} placeholder={placeholder} onChangeText={onChangeText} />;
}

Why good: useOptimistic provides automatic rollback on errors, ref as props eliminates forwardRef boilerplate

</patterns>

---

<red_flags>

RED FLAGS

High Priority Issues:

• Using ScrollView + map() for lists with 50+ items - causes severe performance, use FlashList or FlatList
• Adding key prop to FlashList items - BREAKS cell recycling, eliminates FlashList's main benefit
• Using React Native's built-in SafeAreaView - deprecated in 0.81+, use react-native-safe-area-context
• Not testing on both platforms - iOS/Android differences compound; test daily on both
• Inline functions in FlatList/FlashList renderItem - creates new function every render, breaks memoization
• Using Reanimated 4 with old architecture - Reanimated 4.x is New Architecture ONLY

Medium Priority Issues:

• Hardcoded colors/spacing instead of constants - breaks consistency, makes theming impossible
• Not using Platform.select for shadows - iOS shadow props don't work on Android (use elevation)
• Missing keyboard handling on forms - keyboard covers inputs without KeyboardAvoidingView
• Using TouchableOpacity everywhere - Pressable is more flexible and supports android_ripple

Gotchas & Edge Cases:

• Android fontWeight only supports 'normal' and 'bold' reliably - 100-900 values may not work
• iOS shadow props are completely ignored on Android - must use elevation for Android shadows
• StatusBar backgroundColor only works on Android - iOS uses translucent status bar
• FlatList onEndReached fires immediately if data fits screen - use onEndReachedThreshold carefully
• KeyboardAvoidingView behavior differs: 'padding' for iOS, 'height' for Android
• React Native doesn't have CSS cascade - each component must have complete styles
• Text must be wrapped in <Text> component - raw strings cause crashes
• New Architecture enabled by default in 0.76+ - some older libraries may need updates
• FlashList v2 is New Architecture only - use v1 or FlatList if on old architecture
• React Native 0.78+ uses React 19 - propTypes removed, forwardRef optional
• React 19 adoption in recent SDK versions - check for breaking changes in your dependencies
• Android 15/16 enforces edge-to-edge - must handle safe areas properly
• Reanimated 4 requires react-native-worklets - Reanimated 3 will not work with it installed
• boxShadow and filter props are New Architecture only - not available on legacy architecture
• Reanimated 4: withSpring no longer uses restDisplacementThreshold/restSpeedThreshold - replaced by energyThreshold

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST use FlashList (preferred) or FlatList for lists with more than 20 items - NEVER ScrollView with .map() for long lists)

(You MUST memoize renderItem callbacks and use stable keyExtractor functions - avoid key props on FlashList items as it breaks recycling)

(You MUST use react-native-safe-area-context for safe areas - React Native's built-in SafeAreaView is deprecated in 0.81+ and will be removed)

(You MUST test on BOTH iOS AND Android from day one - platform differences cause bugs)

(You MUST use Platform.select() or platform-specific files for platform differences - shadows, fonts, and feedback differ)

(You MUST be aware the New Architecture is enabled by default since React Native 0.76 - Fabric, TurboModules, and bridgeless mode)

Failure to follow these rules will result in poor performance, platform-specific bugs, and broken UX on mobile devices.

</critical_reminders>