React Native Complete Guide

The ultimate React Native optimization guide combining:

Callstack - Profiling, measurement, and native optimization (27 references)
Vercel - Code patterns, UI, and best practices (36 rules)

When to Apply

Reference these guidelines when:

Debugging slow/janky UI or animations
Optimizing list and scroll performance
Investigating memory leaks (JS or native)
Optimizing app startup time (TTI)
Reducing bundle or app size
Implementing animations with Reanimated
Building UI with native components
Working with React Compiler
Structuring monorepo projects

Priority-Ordered Guidelines

Priority	Category	Impact	Source
1	Core Rendering	CRITICAL	Vercel
2	List Performance	CRITICAL	Both
3	FPS & Re-renders	CRITICAL	Callstack
4	Bundle Size	CRITICAL	Callstack
5	Animation	HIGH	Both
6	Navigation	HIGH	Vercel
7	TTI Optimization	HIGH	Callstack
8	UI Patterns	HIGH	Vercel
9	Native Performance	HIGH	Callstack
10	State Management	MEDIUM	Vercel
11	React Compiler	MEDIUM	Both
12	Memory Management	MEDIUM	Callstack
13	Monorepo	MEDIUM	Vercel

Quick Reference: Code Patterns (Vercel)

Core Rendering (CRITICAL)

rendering-no-falsy-and - Never use && with falsy values (crashes app)
rendering-text-in-text-component - Wrap strings in Text components

List Performance (CRITICAL)

list-performance-virtualize - Use FlashList/LegendList for any list
list-performance-item-memo - Memoize list item components
list-performance-callbacks - Stabilize callback references
list-performance-inline-objects - Avoid inline style objects
list-performance-function-references - Extract functions outside render
list-performance-images - Use compressed, appropriately-sized images
list-performance-item-expensive - Move expensive work outside items
list-performance-item-types - Use item types for heterogeneous lists

Animation (HIGH)

animation-gpu-properties - Animate only transform and opacity
animation-derived-value - Use useDerivedValue for computed animations
animation-gesture-detector-press - Use Gesture.Tap for press animations

Navigation (HIGH)

navigation-native-navigators - Use native stack/tabs over JS navigators

UI Patterns (HIGH)

ui-expo-image - Use expo-image for all images
ui-image-gallery - Use Galeria for lightboxes
ui-pressable - Use Pressable over TouchableOpacity
ui-safe-area-scroll - Use contentInsetAdjustmentBehavior
ui-scrollview-content-inset - Use contentInset for dynamic spacing
ui-menus - Use native context menus (zeego)
ui-native-modals - Use native modals over JS bottom sheets
ui-measure-views - Use onLayout, not measure()
ui-styling - Use StyleSheet.create, gap, borderCurve

State Management (MEDIUM)

react-state-minimize - Derive values, minimize state
react-state-dispatcher - Use dispatch updaters
react-state-fallback - Use fallback pattern for reactive defaults
state-ground-truth - State represents truth, derive visuals

React Compiler (MEDIUM)

react-compiler-destructure-functions - Destructure functions early
react-compiler-reanimated-shared-values - Use .get()/.set() not .value

Monorepo (MEDIUM)

monorepo-native-deps-in-app - Install native deps in app package
monorepo-single-dependency-versions - Single versions across packages

Configuration (LOW)

fonts-config-plugin - Load fonts at build time
imports-design-system-folder - Re-export from design system
js-hoist-intl - Hoist Intl formatter creation

Quick Reference: Profiling & Measurement (Callstack)

FPS & Re-renders (CRITICAL)

# Open React Native DevTools
# Press 'j' in Metro, or shake device → "Open DevTools"

js-profile-react.md - React DevTools profiling
js-measure-fps.md - FPS monitoring
js-react-compiler.md - Automatic memoization
js-atomic-state.md - Jotai/Zustand patterns
js-concurrent-react.md - useDeferredValue, useTransition

Bundle Size (CRITICAL)

npx react-native bundle \
  --entry-file index.js \
  --bundle-output output.js \
  --platform ios \
  --sourcemap-output output.js.map \
  --dev false --minify true

npx source-map-explorer output.js --no-border-checks

bundle-barrel-exports.md - Avoid barrel imports
bundle-analyze-js.md - JS bundle visualization
bundle-tree-shaking.md - Dead code elimination
bundle-r8-android.md - Android code shrinking
bundle-hermes-mmap.md - Disable bundle compression

TTI Optimization (HIGH)

native-measure-tti.md - TTI measurement setup
bundle-hermes-mmap.md - Enable Hermes mmap
Defer non-critical work with InteractionManager

Native Performance (HIGH)

iOS: Xcode Instruments → Time Profiler
Android: Android Studio → CPU Profiler
native-turbo-modules.md - Building fast native modules
native-threading-model.md - Turbo Module threads
native-profiling.md - Platform profiling guides

Memory Management (MEDIUM)

js-memory-leaks.md - JS memory leak hunting
native-memory-leaks.md - Native memory leaks
native-memory-patterns.md - C++/Swift/Kotlin memory

Animations (MEDIUM)

js-animations-reanimated.md - Reanimated worklets

Problem → Solution Mapping

Problem	Vercel Rules	Callstack References
App crashes	`rendering-no-falsy-and`, `rendering-text-in-text-component`	-
List scroll jank	`list-performance-*`	`js-lists-flatlist-flashlist.md`
Animation drops frames	`animation-gpu-properties`	`js-animations-reanimated.md`
Too many re-renders	`react-state-minimize`	`js-profile-react.md`, `js-react-compiler.md`
Slow startup (TTI)	-	`native-measure-tti.md`, `bundle-hermes-mmap.md`
Large app size	-	`bundle-analyze-app.md`, `bundle-r8-android.md`
Memory growing	-	`js-memory-leaks.md`, `native-memory-leaks.md`
TextInput lag	-	`js-uncontrolled-components.md`
Native module slow	-	`native-turbo-modules.md`

File Structure

react-native/
├── SKILL.md          # This file
├── AGENTS.md         # Full 74KB compiled Vercel guide
├── rules/            # 36 individual Vercel rule files
│   ├── list-performance-*.md
│   ├── animation-*.md
│   ├── ui-*.md
│   └── ...
└── references/       # 27 Callstack reference files
    ├── js-*.md
    ├── native-*.md
    ├── bundle-*.md
    └── images/

Attribution

Combined from:

"The Ultimate Guide to React Native Optimization" by Callstack
React Native Skills by Vercel