/mobile-framework-react-native

name: mobile-framework-react-native
description: React Native mobile development patterns - New Architecture (Fabric, TurboModules, JSI), component architecture, React Navigation 7+, FlashList v2 optimization, gestures with Reanimated 4, platform-specific code, React 19 features

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](examples/core.md) - Component architecture, compound components
• [examples/navigation.md](examples/navigation.md) - Type-safe navigation, auth flows, deep linking
• [examples/styling.md](examples/styling.md) - StyleSheet, design tokens, theming, responsive styling
• [examples/performance.md](examples/performance.md) - FlashList, FlatList optimization, memoization
• [reference.md](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 }}
>