AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

react-native-best-practices

Provides React Native performance optimization guidelines for FPS, TTI, bundle size, memory leaks, re-renders, and animations. Applies to tasks involving Hermes optimization, JS thread blocking, bridge overhead, FlashList, native modules, or debugging jank and frame drops.

Original source
callstackincubator
License
MIT
Pinned revision
59e9d17446a248b21d86f078fcd0bd2d36db1ca4

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read callstackincubator--react-native-best-practices at revision 59e9d17446a248b21d86f078fcd0bd2d36db1ca4, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 31

references/js-measure-fps.md


title: Measure JS FPS impact: HIGH tags: fps, performance, monitoring, flashlight

Skill: Measure JS FPS

Monitor and measure JavaScript frame rate to quantify app smoothness and identify performance regressions.

Quick Command

# Method 1: Built-in Perf Monitor
# Shake device → Dev Menu → "Perf Monitor"

# Method 2: Flashlight (Android, detailed reports)
# Install Flashlight from an official, verified release channel first.
flashlight measure

When to Use

  • Animations feel choppy or janky
  • Scrolling is not smooth
  • Need baseline FPS metrics before/after optimization
  • Want to compare performance across builds

Prerequisites

  • React Native app running on device/simulator
  • For Flashlight: Android device (iOS not supported)

Note: This skill involves visual output (FPS graphs, performance overlays). Use agent-device for runnable scenario evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. FPS graph interpretation may still require exported reports or human review. Record concrete FPS ranges, dropped-frame counts, device tier, and build type in text when asking an agent to reason about them.

Step-by-Step Instructions

Method 1: React Perf Monitor (Quick Check)

  1. Open Dev Menu:

    • iOS Simulator: Ctrl + Cmd + Z or Device > Shake
    • Android Emulator: Cmd + M (Mac) / Ctrl + M (Windows)
  2. Select "Perf Monitor"

  3. Observe the overlay showing:

    • UI (Main) thread FPS - Native rendering
    • JS thread FPS - JavaScript execution
    • RAM usage
  4. Hide with "Hide Perf Monitor" from Dev Menu

Interpretation:

  • 60 FPS = Smooth (16.6ms per frame)
  • < 60 FPS = Dropping frames
  • 120 FPS target for high refresh rate devices (8.3ms per frame)

Method 2: Flashlight (Automated Benchmarking)

Android only. Provides detailed reports and JSON export.

Flashlight FlatList vs FlashList Comparison

Flashlight shows comparative performance data:

  • Score (0-100): Overall performance rating (higher is better)
  • Average FPS: Target 60 FPS for smooth scrolling
  • FPS Graph: Real-time frame rate over test duration
  • CPU/RAM metrics: Resource consumption

The image shows FlatList (score: 3) vs FlashList (score: 67) - a dramatic difference visible in both the score and FPS graph.

Installation:

Install Flashlight from the vendor's official release channel before using it. Prefer a package manager or a version-pinned binary with checksum/signature verification. Do not pipe a remote install script directly into a shell.

Usage:

# Start measuring (app must be running on Android)
flashlight measure

Features:

  • Real-time FPS graph
  • Average FPS calculation
  • CPU and RAM metrics
  • Overall performance score
  • JSON export for CI comparison

Important: Disable Dev Mode

Always disable development mode for accurate measurements:

Android:

  1. Open Dev Menu
  2. Settings > JS Dev Mode → OFF

iOS (React Native CLI):

# Clear Metro cache if needed; this is not a production/release switch
npx react-native start --reset-cache
# Then run a Release scheme/build from Xcode or your CI

Expo:

# Start Metro without dev mode
npx expo start --no-dev --minify
# For accurate measurements, use EAS Build for release testing

Code Examples

Identify FPS Drop Source

If UI FPS drops but JS FPS is fine:

  • Native rendering issue
  • Too many views/complex layouts
  • Heavy native animations

If JS FPS drops but UI FPS is fine:

  • JavaScript computation blocking
  • Expensive React re-renders
  • Look for longRunningFunction patterns

If Both drop:

  • Mixed issue, start with JS profiling

Target Frame Budgets

// 60 FPS = 16.6ms per frame
const FRAME_BUDGET_60 = 16.6;

// 120 FPS = 8.3ms per frame  
const FRAME_BUDGET_120 = 8.3;

// If your function takes longer, it will drop frames
const longRunningFunction = () => {
  let i = 0;
  while (i < 1000000000) { // This blocks for seconds!
    i++;
  }
};

Interpreting Results

| FPS Range | User Perception | Action | |-----------|-----------------|--------| | 55-60 | Smooth | Acceptable | | 45-55 | Slight stutter | Investigate | | 30-45 | Noticeable jank | Optimize required | | < 30 | Very choppy | Critical fix needed |

Flashlight CI Integration

# Export measurements to JSON
flashlight measure --output results.json

# Compare builds
flashlight compare baseline.json current.json

Common Pitfalls

  • Measuring in dev mode: Results will be artificially slow
  • Not using real device: Simulators don't reflect real performance
  • Ignoring UI thread: React Native has two threads - JS issues don't always show on UI thread
  • Single measurement: Run multiple times, FPS varies

Related Skills