react-native-best-practices

React Native Best Practices

Overview

Performance optimization guide for React Native applications, covering JavaScript/React, Native (iOS/Android), and bundling optimizations. Based on Callstack's "Ultimate Guide to React Native Optimization".

Skill Format

Each reference file follows a hybrid format for fast lookup and deep understanding:

• Quick Pattern: Incorrect/Correct code snippets for immediate pattern matching
• Quick Command: Shell commands for process/measurement skills
• Quick Config: Configuration snippets for setup-focused skills
• Quick Reference: Summary tables for conceptual skills
• Deep Dive: Full context with When to Use, Prerequisites, Step-by-Step, Common Pitfalls

Impact ratings: CRITICAL (fix immediately), HIGH (significant improvement), MEDIUM (worthwhile optimization)

When to Apply

Reference these guidelines when:

• Debugging slow/janky UI or animations
• Investigating memory leaks (JS or native)
• Optimizing app startup time (TTI)
• Reducing bundle or app size
• Writing native modules (Turbo Modules)
• Profiling React Native performance
• Reviewing React Native code for performance

Security Notes

• Treat shell commands in these references as local developer operations. Review them before running, prefer version-pinned tooling, and avoid piping remote scripts directly to a shell.
• Treat third-party libraries and plugins as dependencies that still require normal supply-chain controls: pin versions, verify provenance, and update through your standard review process.
• Treat Re.Pack code splitting as first-party artifact delivery only. Remote chunks must come from trusted HTTPS origins you control and be pinned to the current app release.

Priority-Ordered Guidelines

Quick Reference

Optimization Workflow

Follow this cycle for any performance issue: Measure → Optimize → Re-measure → Validate

1. Measure: Capture baseline metrics before changes. For runtime issues, prefer commit timeline, re-render counts, slow components, heaviest-commit breakdown, and startup/TTI when available. Component tree depth or count are optional context, not substitutes.
2. Optimize: Apply the targeted fix from the relevant reference
3. Re-measure: Run the same measurement to get updated metrics
4. Validate: Confirm improvement (e.g., FPS 45→60, TTI 3.2s→1.8s, bundle 2.1MB→1.6MB)

If metrics did not improve, revert and try the next suggested fix.

Review Guardrails

• Check library versions before suggesting API-specific fixes. Example: FlashList v2 deprecates estimatedItemSize, so do not flag it as missing there.
• Do not suggest useMemo or useCallback dependency changes unless behavior is demonstrably incorrect or profiling shows wasted work tied to that value.
• Do not report stale closures speculatively. Show the stale read path, a repro, or profiler evidence before calling it out.
• When profiling a flow, measure the target interaction itself. Do not treat component tree depth or component count as the main performance evidence.

Critical: FPS & Re-renders

Profile first:

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

Common fixes:

• Replace ScrollView with FlatList/FlashList for lists
• Use React Compiler for automatic memoization
• Use atomic state (Jotai/Zustand) to reduce re-renders
• Use useDeferredValue for expensive computations

Critical: Bundle Size

Analyze bundle:

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

Verify improvement after optimization:

# Record baseline size before changes
ls -lh output.js  # e.g., Before: 2.1 MB

# After applying fixes, re-bundle and compare
npx react-native bundle --entry-file index.js --bundle-output output.js \
  --platform ios --dev false --minify true
ls -lh output.js  # e.g., After: 1.6 MB  (24% reduction)

Common fixes:

• Avoid barrel imports (import directly from source)
• Remove unnecessary Intl polyfills only after checking Hermes API and method coverage
• Enable tree shaking (Expo SDK 52+ or Re.Pack)
• Enable R8 for Android native code shrinking

High: TTI Optimization

Measure TTI:

• Use react-native-performance for markers
• Only measure cold starts (exclude warm/hot/prewarm)

Common fixes:

• Disable JS bundle compression on Android (enables Hermes mmap)
• Use native navigation (react-native-screens)
• Preload commonly-used expensive screens before navigating to them

High: Native Performance

Profile native:

• iOS: Xcode Instruments → Time Profiler
• Android: Android Studio → CPU Profiler

Common fixes:

• Use background threads for heavy native work
• Prefer async over sync Turbo Module methods
• Use C++ for cross-platform performance-critical code

References

Full documentation with code examples in [references/][references]:

JavaScript/React (js-*)

Native (native-*)

Bundling (bundle-*)

Searching References

# Find patterns by keyword
grep -l "reanimated" references/
grep -l "flatlist" references/
grep -l "memory" references/
grep -l "profil" references/
grep -l "tti" references/
grep -l "bundle" references/

Problem → Skill Mapping

[references]: references/ [js-lists-flatlist-flashlist]: references/js-lists-flatlist-flashlist.md [js-profile-react]: references/js-profile-react.md [js-measure-fps]: references/js-measure-fps.md [js-memory-leaks]: references/js-memory-leaks.md [js-atomic-state]: references/js-atomic-state.md [js-concurrent-react]: references/js-concurrent-react.md [js-react-compiler]: references/js-react-compiler.md [js-animations-reanimated]: references/js-animations-reanimated.md [js-bottomsheet]: references/js-bottomsheet.md [js-uncontrolled-components]: references/js-uncontrolled-components.md [native-turbo-modules]: references/native-turbo-modules.md [native-sdks-over-polyfills]: references/native-sdks-over-polyfills.md [native-measure-tti]: references/native-measure-tti.md [native-threading-model]: references/native-threading-model.md [native-profiling]: references/native-profiling.md [native-platform-setup]: references/native-platform-setup.md [native-view-flattening]: references/native-view-flattening.md [native-memory-patterns]: references/native-memory-patterns.md [native-memory-leaks]: references/native-memory-leaks.md [native-android-16kb-alignment]: references/native-android-16kb-alignment.md [bundle-barrel-exports]: references/bundle-barrel-exports.md [bundle-analyze-js]: references/bundle-analyze-js.md [bundle-tree-shaking]: references/bundle-tree-shaking.md [bundle-analyze-app]: references/bundle-analyze-app.md [bundle-r8-android]: references/bundle-r8-android.md [bundle-hermes-mmap]: references/bundle-hermes-mmap.md [bundle-native-assets]: references/bundle-native-assets.md [bundle-library-size]: references/bundle-library-size.md [bundle-code-splitting]: references/bundle-code-splitting.md

Attribution

Based on "The Ultimate Guide to React Native Optimization" by Callstack.