Expo Best Practices

Comprehensive best practices for building production Expo and React Native applications with TypeScript, Expo SDK 52+, and React Navigation.

When to Apply

Reference these guidelines when:

• >Writing new React Native components or screens
• >Implementing navigation patterns
• >Optimizing FlatList and list performance
• >Managing offline state and AsyncStorage
• >Handling platform-specific code (iOS/Android)
• >Working with native APIs and permissions
• >Setting up OTA updates with EAS Update

Guide Categories by Priority

Quick Reference

1. Performance Optimization (CRITICAL)

• >performance-list-optimization - FlatList/FlashList tuning for smooth 60fps scrolling
• >performance-image-handling - Image caching, placeholders, and blurhash with expo-image
• >performance-memory-management - Preventing memory leaks, cleanup patterns
• >performance-animation-bridge - UI thread animations with Reanimated, avoiding bridge overhead

2. Navigation Patterns (HIGH)

• >navigation-stack-patterns - Native stack vs JS stack, screen options, gestures
• >navigation-deep-linking - Universal links, URL schemes, Expo Router linking
• >navigation-tab-optimization - Lazy tabs, unmountOnBlur, preloading strategies

3. State Management (HIGH)

• >state-async-storage - AsyncStorage patterns and MMKV as fast alternative
• >state-context-patterns - Context splitting for mobile performance
• >state-offline-first - Offline-first architecture with optimistic updates

4. Custom Hooks for Native (MEDIUM-HIGH)

• >hooks-native-apis - Camera, location, notifications hooks with cleanup
• >hooks-permissions - Permission request patterns with rationale dialogs
• >hooks-app-lifecycle - AppState changes, background/foreground detection

5. Platform-Specific Code (MEDIUM)

• >platform-specific-code - Platform.select, Platform.OS, and .ios.tsx/.android.tsx files
• >platform-safe-areas - SafeAreaView and useSafeAreaInsets patterns
• >platform-gestures - Gesture handler patterns for iOS/Android differences

6. Error Handling & Resilience (MEDIUM)

• >error-crash-reporting - Sentry integration, error tracking, breadcrumbs
• >error-network-resilience - Retry logic, timeout handling, offline detection
• >error-boundaries-native - Error boundaries adapted for React Native screens

7. OTA Updates (MEDIUM)

• >ota-updates-expo - EAS Update setup, rollback strategies, update channels
• >ota-versioning - Runtime versioning, native compatibility checks

8. Testing (LOW-MEDIUM)

• >testing-detox-patterns - E2E testing with Detox for iOS/Android
• >testing-component-native - React Native Testing Library patterns

9. Accessibility (LOW-MEDIUM)

• >a11y-screen-readers - VoiceOver/TalkBack support, accessibilityLabel/Role/Hint
• >a11y-touch-targets - Minimum 44x44 touch targets, hitSlop patterns
• >a11y-dynamic-type - Dynamic type support, scaled fonts, layout adaptation

How to Use

Read individual guide files for detailed explanations and code examples:

guides/performance-list-optimization.md
guides/navigation-stack-patterns.md

Each guide file contains:

• >Brief explanation of why it matters
• >Incorrect code example with explanation
• >Correct code example with explanation
• >Additional context and references

Full Compiled Document

For the complete guide with all content expanded: AGENTS.md