expo-react-native-best-practices

name	expo-react-native-best-practices
description	Expo React Native performance optimization guidelines. This skill should be used when writing, reviewing, or refactoring Expo/React Native code to ensure optimal performance patterns. Triggers on tasks involving React Native components, Expo Router navigation, list rendering, image optimization, bundle size, or mobile app performance improvements.

Expo React Native Best Practices

Comprehensive performance optimization guide for Expo and React Native applications. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new React Native components or Expo screens
• Implementing list rendering (FlatList, FlashList)
• Optimizing images and assets
• Reviewing code for performance issues
• Refactoring existing Expo/React Native code
• Setting up navigation with Expo Router
• Reducing bundle size or improving startup time

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	List Rendering	CRITICAL	list-
2	Image Optimization	CRITICAL	image-
3	Bundle Size	HIGH	bundle-
4	Navigation	HIGH	nav-
5	Re-render Optimization	MEDIUM	rerender-
6	Startup Performance	MEDIUM	startup-
7	Memory Management	MEDIUM	memory-
8	Native Modules	LOW-MEDIUM	native-

Quick Reference

1. List Rendering (CRITICAL)

• list-use-flashlist - Use FlashList instead of FlatList for large lists
• list-getitemlayout - Implement getItemLayout to skip measurement
• list-memo-items - Memoize list item components with React.memo()
• list-callback-renderitem - Use useCallback for renderItem function
• list-keyextractor - Use stable keyExtractor instead of index
• list-windowsize - Adjust windowSize for memory/rendering balance

2. Image Optimization (CRITICAL)

• image-use-expo-image - Use expo-image instead of RN Image
• image-optimize-assets - Use npx expo-optimize for compression
• image-recycling-key - Use recyclingKey in recycling lists
• image-priority - Set image priority for loading order
• image-placeholder - Use blurhash/thumbhash for placeholders
• image-cache-policy - Configure appropriate cache policies

3. Bundle Size (HIGH)

• bundle-tree-shaking - Enable tree shaking for dead code elimination
• bundle-direct-imports - Import directly, avoid barrel files
• bundle-lazy-load - Lazy load heavy screens and components
• bundle-analyze - Use expo-bundle-analyzer to audit size
• bundle-split-chunks - Split vendor and app code appropriately

4. Navigation (HIGH)

• nav-expo-router - Use Expo Router for file-based routing
• nav-lazy-screens - Lazy load screens not immediately needed
• nav-nested-navigators - Properly structure nested navigators
• nav-screen-options - Use screenOptions for consistent headers
• nav-deep-linking - Configure deep linking for better UX

5. Re-render Optimization (MEDIUM)

• rerender-memo - Use React.memo() for expensive components
• rerender-usecallback - Wrap callbacks with useCallback
• rerender-usememo - Memoize expensive computations
• rerender-context-split - Split context to avoid unnecessary updates
• rerender-zustand - Consider Zustand for performant state management

6. Startup Performance (MEDIUM)

• startup-splash-screen - Keep splash screen until assets ready
• startup-font-loading - Load fonts efficiently with expo-font
• startup-defer-init - Defer non-critical initialization
• startup-preload-assets - Preload critical assets before render

7. Memory Management (MEDIUM)

• memory-cleanup-effects - Clean up effects properly on unmount
• memory-avoid-closures - Avoid creating closures in render
• memory-large-data - Paginate large data sets
• memory-image-cleanup - Clear image cache when appropriate

8. Native Modules (LOW-MEDIUM)

• native-hermes - Use Hermes engine for better performance
• native-new-arch - Enable New Architecture when stable
• native-bridge-minimize - Minimize bridge crossings
• native-worklets - Use Reanimated worklets for animations

How to Use

Read individual rule files for detailed explanations and code examples:

rules/list-use-flashlist.md
rules/image-use-expo-image.md
rules/_sections.md

Each rule 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 rules expanded: AGENTS.md