react-native-best-practices

name: react-native-best-practices
description: 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.
license: MIT
author: Callstack
keywords: ["react-native", "expo", "performance", "optimization", "profiling"]

Onboarding

Step 1: Validate React Native Setup

Before applying performance optimizations, ensure:

• Expo CLI or React Native CLI is installed
  • Verify with: npx expo --version and npx react-native --version
• Metro bundler is running (apply only for bundle analysis)
• React Native DevTools profiling is available through agent-device react-devtools (apply only for React render profiling/debugging)
  • Run agent-device react-devtools status, then agent-device react-devtools wait --connected

Security Guardrails

• Review shell commands before running them and prefer version-pinned tooling from trusted sources.
• Do not pipe remote install scripts directly into a shell.
• Treat third-party packages as normal supply-chain dependencies that require provenance and version review.
• If using remote chunk loading, prefer app-bundled chunks or signed CI release manifests; hosted chunks must be first-party artifacts tied to the current release.

When to Load Reference Files

Load specific reference files from references/ based on the task:

JavaScript/React Performance (js-*)

• Debugging slow/janky UI or animations → references/js-measure-fps.md
• Investigating re-render issues → references/js-profile-react.md → references/js-react-compiler.md
• Optimizing list scrolling → references/js-lists-flatlist-flashlist.md
• Reducing re-renders with state management → references/js-atomic-state.md
• Using Concurrent React features → references/js-concurrent-react.md
• Enabling automatic memoization → references/js-react-compiler.md
• Optimizing animations → references/js-animations-reanimated.md
• Fixing TextInput lag → references/js-uncontrolled-components.md
• Hunting JavaScript memory leaks → references/js-memory-leaks.md

Native Performance (native-*)

• Measuring startup time (TTI) → references/native-measure-tti.md
• Building native modules → references/native-turbo-modules.md
• Understanding native threading → references/native-threading-model.md
• Profiling native code → references/native-profiling.md
• Setting up native tooling → references/native-platform-setup.md
• Debugging view hierarchy → references/native-view-flattening.md
• Native memory patterns → references/native-memory-patterns.md
• Hunting native memory leaks → references/native-memory-leaks.md
• Choosing native SDKs vs polyfills → references/native-sdks-over-polyfills.md
• Fixing Android 16KB alignment → references/native-android-16kb-alignment.md

Bundle & App Size (bundle-*)

• Analyzing bundle size → references/bundle-analyze-js.md
• Analyzing app size → references/bundle-analyze-app.md
• Fixing barrel imports → references/bundle-barrel-exports.md
• Enabling tree shaking → references/bundle-tree-shaking.md
• Android code shrinking → references/bundle-r8-android.md
• Optimizing Hermes bundle loading → references/bundle-hermes-mmap.md
• Managing native assets → references/bundle-native-assets.md
• Evaluating library size → references/bundle-library-size.md
• Code splitting → references/bundle-code-splitting.md

Problem → Reference Mapping

Use this quick lookup when debugging specific issues:

Quick Reference Commands

FPS & Re-renders

agent-device react-devtools status
agent-device react-devtools wait --connected
agent-device react-devtools profile start
agent-device react-devtools profile stop
agent-device react-devtools profile slow --limit 5
agent-device react-devtools profile rerenders --limit 5
agent-device react-devtools profile timeline --limit 20

Drive the target interaction with normal agent-device commands between profile start and profile stop.

Manual fallback when agent-device is unavailable: open React Native DevTools from Metro (j) or the Dev Menu, use the Profiler tab, and record the same interaction.

For release-build React component profiling, connect @callstack/inspector first so React DevTools can attach to the release app, then run the agent-device react-devtools flow above.

Baseline runtime metrics should come from the target interaction itself:

• Capture commit timeline, re-render counts, slow components, and heaviest-commit breakdown.
• Treat component tree depth and count as supporting context only.

Common fixes:

• Replace ScrollView with FlatList/FlashList for lists
• After profiling shows cascading re-renders, use React Compiler for automatic memoization
• After profiling shows broad store/context updates, use atomic state (Jotai/Zustand) to reduce re-renders
• Use useDeferredValue for expensive computations

Review guardrails:

• Check library versions before suggesting API-specific fixes. FlashList v2 deprecates estimatedItemSize.
• Do not suggest useMemo or useCallback dependency changes without a reproducible correctness issue or profiling evidence.
• Do not report stale closures unless the stale read path or repro is clear.

Analyze Bundle Size

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

Common fixes:

• Avoid barrel imports (import directly from source)
• Remove unnecessary Intl polyfills only after checking Hermes API and method coverage
• Evaluate tree shaking (Expo SDK 52+ experimental unused import/export removal, or Re.Pack only if already configured)
• Enable R8 for Android native code shrinking

Measure TTI

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

Common fixes:

• For React Native 0.78 and earlier, disable Android JS bundle compression to enable Hermes mmap
• Use native navigation (react-native-screens)
• Preload commonly-used expensive screens before navigating to them

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

Priority Guidelines

Apply optimizations in this order:

Attribution

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

interface:
  display_name: "React Native Best Practices"
  short_description: "React Native performance optimization guide"
  default_prompt: "Use $react-native-best-practices to diagnose and improve React Native performance."

title: Analyze App Bundle Size
impact: HIGH
tags: app-size, ruler, emerge-tools, thinning

Skill: Analyze App Bundle Size

Measure iOS and Android app download/install sizes using Ruler, App Store Connect, and Emerge Tools.

Quick Command

# Android (Ruler)
cd android && ./gradlew analyzeReleaseBundle

# iOS (Xcode export with thinning)
cd ios && xcodebuild -exportArchive \
  -archivePath MyApp.xcarchive \
  -exportPath ./export \
  -exportOptionsPlist ExportOptions.plist
# Check: App Thinning Size Report.txt

When to Use

• App download size is too large
• Users complain about storage usage
• App approaching store limits
• Comparing releases for size regression

Note: This skill involves visual size reports (Ruler, Emerge Tools X-Ray). When regression checks include device flows, use agent-device for app evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. Size report analysis itself may still require exported reports, browser screenshots, or human review. Record concrete module/file names and before/after artifact sizes in text when asking an agent to reason about them.

Key Metrics

Google finding: Every 6 MB increase reduces installs by 1%.

Android: Ruler (Spotify)

Setup

Add to android/build.gradle:

buildscript {
    dependencies {
        classpath("com.spotify.ruler:ruler-gradle-plugin:2.0.0-beta-3")
    }
}

Add to android/app/build.gradle:

apply plugin: "com.spotify.ruler"

ruler {
    abi.set("arm64-v8a")  // Target architecture
    locale.set("en")
    screenDensity.set(480)
    sdkVersion.set(34)
}

Analyze

cd android
./gradlew analyzeReleaseBundle

Opens HTML report with:

• Download size
• Install size
• Component breakdown (biggest → smallest)

CI Size Validation

ruler {
    verification {
        downloadSizeThreshold = 20 * 1024 * 1024  // 20 MB
        installSizeThreshold = 50 * 1024 * 1024   // 50 MB
    }
}

Build fails if thresholds exceeded.

iOS: Xcode App Thinning

Via App Store Connect (Most Accurate)

After uploading to TestFlight:

1. Open App Store Connect
2. Go to your build
3. View size table by device variant

Note: TestFlight builds include debug data, App Store builds slightly larger due to DRM.

Via Xcode Export

Export an archive with app thinning enabled for all compatible device variants.

Or in ExportOptions.plist:

<key>thinning</key>
<string>&lt;thin-for-all-variants&gt;</string>

Output

Creates folder with:

• Universal IPA: All variants combined
• Thinned IPAs: One per device variant
• App Thinning Size Report.txt:

Variant: SampleApp-<UUID>.ipa
App + On Demand Resources size: 3.5 MB compressed, 10.6 MB uncompressed
App size: 3.5 MB compressed, 10.6 MB uncompressed

• Compressed = Download size
• Uncompressed = Install size

Emerge Tools (Cross-Platform)

Third-party service with visual analysis.

Upload

Upload IPA, APK, or AAB through their web interface or CI integration.

Features

Emerge Tools X-Ray for iOS (images/emerge-xray-ios.png)

• X-Ray: Treemap visualization (like source-map-explorer for binaries)
  • Shows Frameworks (hermes.framework), Mach-O sections (TEXT, DATA), etc.
  • Color-coded: Binaries, Localizations, Fonts, Asset Catalogs, Videos, CoreML Models
  • Visible components: main.jsbundle (JS code), RCT modules, DYLD sections
• Breakdown: Component-by-component size
• Insights: Automated suggestions (use with caution)

Caution: Some suggestions may not apply to React Native (e.g., "remove Hermes").

Size Comparison

Typical React Native App Sizes

Baseline empty app: ~6-10 MB download

Optimization Impact Example

Quick Commands

# Android release bundle size
cd android && ./gradlew bundleRelease
# Check: android/app/build/outputs/bundle/release/

# iOS archive
cd ios && xcodebuild -workspace ios/MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Release \
  -archivePath MyApp.xcarchive \
  archive

# Export with thinning report
cd ios && xcodebuild -exportArchive \
  -archivePath MyApp.xcarchive \
  -exportPath ./export \
  -exportOptionsPlist ExportOptions.plist

Related Skills

• bundle-r8-android.md (./bundle-r8-android.md) - Reduce Android size
• bundle-native-assets.md (./bundle-native-assets.md) - Optimize asset delivery
• bundle-analyze-js.md (./bundle-analyze-js.md) - JS bundle analysis

title: Analyze JS Bundle Size
impact: CRITICAL
tags: bundle, analysis, source-map-explorer, expo-atlas

Skill: Analyze JS Bundle Size

Use source-map-explorer and Expo Atlas to visualize what's in your JavaScript bundle.

Quick Command

# React Native CLI
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

# Expo
EXPO_UNSTABLE_ATLAS=true npx expo export --platform ios && npx expo-atlas

When to Use

• JS bundle seems too large
• Want to identify heavy dependencies
• Investigating startup time issues
• Before/after optimization comparison

Note: This skill involves visual treemap output (source-map-explorer, Expo Atlas). When regression checks include device flows, use agent-device for app evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. Treemap analysis itself may still require exported reports, browser screenshots, or human review. Record the largest modules and before/after bundle sizes in text when asking an agent to reason about them.

Understanding Hermes Bytecode

Release builds using Hermes, the default engine in modern React Native, ship Hermes bytecode rather than raw JavaScript:

• Skips parsing at runtime
• Still benefits from smaller bundles
• Heavy imports still execute on startup

Impact of bundle size:

• Larger bytecode = longer download from store
• More imports on init path = slower TTI

Development builds fetch JS from the dev server, and non-Hermes engines have different startup tradeoffs. Smaller bytecode helps app size and startup, but startup also depends on what executes on the initialization path. Imports that eagerly touch native modules can defeat Turbo Module lazy loading and hurt TTI.

Method 1: source-map-explorer

Generate Bundle with Source Map

React Native CLI:

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

Expo (SDK 51+):

npx expo export --platform ios --source-maps --output-dir dist
# Bundle at: dist/ios/_expo/static/js/ios/*.js
# Source map at: dist/ios/_expo/static/js/ios/*.map

Analyze

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

Note: --no-border-checks needed due to Metro's non-standard source maps.

Opens browser with treemap visualization:

Bundle Treemap from source-map-explorer (images/bundle-treemap-source-map-explorer.png)

The treemap shows:

• Hierarchy: node_modules/ → react-native/ → Libraries/ → individual files
• Size: Box area proportional to file size (KB shown in labels)
• Major components visible:
  • react-native (724.18 KB, 80.5%)
  • Renderer (208.44 KB) - ReactNativeRenderer-prod.js, ReactFabric-prod.js
  • Components (125.29 KB) - Touchable, ScrollView, etc.
  • Animated (79.48 KB) - Animation system
  • virtualized-lists (57.57 KB) - FlatList internals

Click on any section to drill down into that directory.

Limitation: May lose ~30% info due to mapping issues.

Method 2: Expo Atlas

More accurate for Expo projects (or with workaround for bare RN).

For Expo Projects

# Start with Atlas enabled
EXPO_UNSTABLE_ATLAS=true npx expo start --no-dev

# Or export
EXPO_UNSTABLE_ATLAS=true npx expo export

Then launch UI:

npx expo-atlas

Expo Atlas Treemap (images/expo-atlas-treemap.png)

Expo Atlas provides more accurate visualization for Expo projects, with similar treemap interface showing module sizes and dependencies.

For Non-Expo Projects

Use expo-atlas-without-expo package.

Method 3: Re.Pack Bundle Analysis (Webpack/Rspack)

If using Re.Pack:

webpack-bundle-analyzer

rspack build --analyze

bundle-stats / statoscope

# Generate stats
npx react-native bundle \
  --platform android \
  --entry-file index.js \
  --dev false \
  --minify true \
  --json stats.json

# Analyze
npx bundle-stats --html --json stats.json

Rsdoctor

// rspack.config.js
const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin');

module.exports = {
  plugins: [
    process.env.RSDOCTOR && new RsdoctorRspackPlugin(),
  ].filter(Boolean),
};

Run with:

RSDOCTOR=true npx react-native start

What to Look For

Red Flags

Common Offenders

• Lodash full import: Prefer built-ins or specific imports
• Moment.js: Replace with date-fns or dayjs
• Intl polyfills: Check Hermes API and method coverage before removing them
• AWS SDK: Import specific services only

Code Examples

Identify Barrel Import Impact

// BAD: Imports entire library through barrel
import { format } from 'date-fns';

// In bundle: All of date-fns loaded

// GOOD: Direct import
import format from 'date-fns/format';

// In bundle: Only format function

Comparing Bundles

source-map-explorer

# Generate baseline
npx react-native bundle ... --bundle-output baseline.js --sourcemap-output baseline.js.map

# Make changes, generate new bundle
npx react-native bundle ... --bundle-output current.js --sourcemap-output current.js.map

# Compare manually in browser

Re.Pack (automated)

npx bundle-stats compare baseline-stats.json current-stats.json

Quick Commands

React Native CLI:

# iOS bundle analysis
npx react-native bundle \
  --entry-file index.js \
  --bundle-output ios-bundle.js \
  --platform ios \
  --sourcemap-output ios-bundle.js.map \
  --dev false \
  --minify true && \
npx source-map-explorer ios-bundle.js --no-border-checks

# Android bundle analysis  
npx react-native bundle \
  --entry-file index.js \
  --bundle-output android-bundle.js \
  --platform android \
  --sourcemap-output android-bundle.js.map \
  --dev false \
  --minify true && \
npx source-map-explorer android-bundle.js --no-border-checks

Expo:

# Use Expo Atlas (recommended for Expo projects)
EXPO_UNSTABLE_ATLAS=true npx expo export --platform ios
npx expo-atlas

Related Skills

• bundle-barrel-exports.md (./bundle-barrel-exports.md) - Fix barrel import issues
• bundle-tree-shaking.md (./bundle-tree-shaking.md) - Enable dead code elimination
• bundle-library-size.md (./bundle-library-size.md) - Check library sizes before adding

title: Avoid Barrel Exports
impact: CRITICAL
tags: bundle, imports, barrel, tree-shaking

Skill: Avoid Barrel Exports

Refactor barrel imports (index files) to reduce bundle size and improve startup time.

Quick Pattern

Incorrect:

import { Button } from './components';
// Loads ALL exports from components/index.ts

Correct:

import Button from './components/Button';
// Loads only Button

When to Use

• Bundle contains unused code from libraries
• Circular dependency warnings in Metro
• Hot Module Replacement (HMR) breaks frequently
• TTI is slow due to module evaluation

What Are Barrel Exports?

// components/index.ts (barrel file)
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';
export { Sidebar } from './Sidebar';

// Usage (barrel import)
import { Button } from './components';

Problems with Barrel Imports

1. Bundle Size Overhead

Without effective tree shaking or a library-specific Babel plugin, barrel imports can make all re-exported modules reachable and evaluated even when only one export is used:

// Only need Button, but entire barrel is bundled
import { Button } from './components';
// Card, Modal, Sidebar also included!

2. Runtime Overhead

All modules evaluate before returning your import:

import { Button } from './components';
// JavaScript must evaluate:
// - Button.tsx
// - Card.tsx
// - Modal.tsx  
// - Sidebar.tsx
// Even though you only use Button

3. Circular Dependencies

Barrel files make cycles easier to create accidentally:

Warning: Require cycle:
  components/index.ts -> Button.tsx -> utils/index.ts -> components/index.ts

Breaks HMR, causes unpredictable behavior.

Solution 1: Direct Imports

Replace barrel imports with direct paths:

// BEFORE: Barrel import
import { Button, Card } from './components';

// AFTER: Direct imports
import Button from './components/Button';
import Card from './components/Card';

Enforce with ESLint

npm install -D eslint-plugin-no-barrel-files

// eslint.config.js
import noBarrelFiles from 'eslint-plugin-no-barrel-files';

export default [
  {
    plugins: { 'no-barrel-files': noBarrelFiles },
    rules: {
      'no-barrel-files/no-barrel-files': 'error',
    },
  },
];

Solution 2: Tree Shaking (Automatic)

Enable tree shaking to automatically remove unused barrel exports.

Expo SDK 52+

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);

config.transformer.getTransformOptions = async () => ({
  transform: {
    experimentalImportSupport: true,
  },
});

module.exports = config;

# .env
EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
EXPO_UNSTABLE_TREE_SHAKING=1

metro-serializer-esbuild

npm install @rnx-kit/metro-serializer-esbuild

Re.Pack (Webpack/Rspack)

Tree shaking built-in.

Real-World Example: date-fns

// BAD: Imports entire library
import { format, addDays, isToday } from 'date-fns';

// GOOD: Direct imports
import format from 'date-fns/format';
import addDays from 'date-fns/addDays';
import isToday from 'date-fns/isToday';

If the project uses a bundler/configuration with working tree shaking, top-level ESM imports from libraries such as date-fns may be optimized automatically. Without that, submodule imports are still the safer pattern. Measure with bundle analysis.

Library-Specific Solutions

Some libraries provide Babel plugins:

React Native Paper

// babel.config.js
module.exports = {
  plugins: [
    'react-native-paper/babel',  // Auto-transforms imports
  ],
};

Transforms:

import { Button } from 'react-native-paper';
// Into:
import Button from 'react-native-paper/lib/module/components/Button';

Refactoring Strategy

Step 1: Identify Barrel Files

Look for index.ts files with multiple exports:

grep -r "export \* from" src/
grep -r "export { .* } from" src/

Step 2: Update Imports

// Find all usages
// VS Code: Cmd+Shift+F for "from './components'"

// Replace each with direct import
import Button from './components/Button';

Step 3: (Optional) Keep Barrel for External API

If your package is consumed by others:

// Keep index.ts for package API
// components/index.ts
export { Button } from './Button';

// Internal code uses direct imports
// src/screens/Home.tsx
import Button from '../components/Button';

Migration Script Example

# Use codemod or search-replace
# Find: import { (\w+) } from '\.\/components';
# Replace: import $1 from './components/$1';

Verification

After refactoring:

1. Run bundle analysis (see bundle-analyze-js.md (./bundle-analyze-js.md))
2. Compare sizes before/after
3. Check for circular dependency warnings

Common Pitfalls

• Breaking external consumers: If publishing a library, keep barrel for public API
• IDE auto-imports: Configure IDE to prefer direct imports
• Inconsistent patterns: Enforce with ESLint across team

Related Skills

• bundle-analyze-js.md (./bundle-analyze-js.md) - Verify impact
• bundle-tree-shaking.md (./bundle-tree-shaking.md) - Automatic solution
• bundle-library-size.md (./bundle-library-size.md) - Check library patterns

title: Remote Chunk Loading
impact: MEDIUM
tags: code-splitting, lazy-loading, chunks, release-artifacts, remote-code

Skill: Remote Chunk Loading

Harden remote JavaScript chunk loading when a React Native app already uses Re.Pack or has an explicit remote-code-loading requirement.

Quick Pattern

Before (static import):

import SettingsScreen from './screens/SettingsScreen';

After (lazy loaded chunk):

const SettingsScreen = React.lazy(() =>
  import(/* webpackChunkName: "settings" */ './screens/SettingsScreen')
);

<Suspense fallback={<Loading />}>
  <SettingsScreen />
</Suspense>

When to Use

Consider code splitting when:

• Not using Hermes (JSC/V8 benefits more)
• App size approaches app-store or base-module limits
• The app already has a micro-frontend architecture
• Loading features based on user permissions
• Other bundle-size optimizations are exhausted
• Remote delivery is an explicit product or release requirement

Do not recommend adopting Re.Pack for ordinary bundle-size work. Keep the default path on Metro/Expo unless remote chunk loading is already present or specifically required.

Note: Hermes already uses memory mapping for efficient bundle reading. Benefits of code splitting are minimal with Hermes or even counterproductive in some cases.

Security Model

Chunks are executable application code. Prefer chunks packaged with the app or resolved from a release manifest produced by your CI. Hosted chunks are acceptable only when they are first-party release artifacts, not arbitrary runtime URLs.

Keep these guardrails in place:

• Serve chunks only from a first-party, HTTPS-only origin you control
• Resolve scriptId through a fixed allowlist or signed release manifest
• If using Re.Pack, enable code signing for remotely hosted chunks and use strict signature verification in production
• Fail closed if a chunk is missing or unexpected
• Do not load chunks from user-controlled input, query params, or third-party domains

Prerequisites

• Project already uses Re.Pack, or remote chunk loading is an explicit requirement approved after measuring simpler alternatives
• Remote chunks are produced by the same release pipeline as the app
• Chunk locations come from a fixed allowlist or signed release manifest

If the project does not already use Re.Pack, do not start here. First confirm Metro/Expo bundle analysis, import cleanup, asset cleanup, native app-size work, and store delivery constraints.

Step-by-Step Instructions

1. Create Split Point with React.lazy

// BEFORE: Static import
import SettingsScreen from './screens/SettingsScreen';

// AFTER: Dynamic import (creates split point)
const SettingsScreen = React.lazy(() =>
  import(/* webpackChunkName: "settings" */ './screens/SettingsScreen')
);

2. Wrap with Suspense

import React, { Suspense } from 'react';

const App = () => {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <SettingsScreen />
    </Suspense>
  );
};

3. Configure Chunk Loading

// index.js (before AppRegistry)
import { ScriptManager, Script } from '@callstack/repack/client';

const RELEASE_CHUNKS = Object.freeze({
  settings: {
    release: '42',
  },
});

ScriptManager.shared.addResolver(async (scriptId) => {
  if (__DEV__) {
    return {
      url: Script.getDevServerURL(scriptId),
      cache: false,
    };
  }

  const chunk = RELEASE_CHUNKS[scriptId];

  if (!chunk) {
    throw new Error(`Unknown chunk: ${scriptId}`);
  }

  return {
    url: Script.getRemoteURL(
      getFirstPartyChunkBaseURL(scriptId, chunk.release)
    ),
    verifyScriptSignature: 'strict',
  };
});

function getFirstPartyChunkBaseURL(scriptId, release) {
  // App-owned helper: read a signed CI manifest and return the first-party
  // base URL without ".chunk.bundle"; Script.getRemoteURL appends it.
  // Do not accept hostnames, paths, or script IDs from runtime input.
  return ReleaseManifest.getChunkBaseURL({ scriptId, release });
}

AppRegistry.registerComponent(appName, () => App);

For app-bundled chunks in a Re.Pack project, configure extraChunks with type: 'local' and resolve those script IDs from the filesystem:

if (LOCAL_CHUNKS.has(scriptId)) {
  return {
    url: Script.getFileSystemURL(scriptId),
    absolute: true,
  };
}

4. Build and Deploy Chunks

Build generates:

• index.bundle - Main bundle
• settings.chunk.bundle - Lazy-loaded chunk

Remote chunks are written to build/output/<platform>/remotes by default. Deploy chunks as first-party release artifacts. Prefer app-bundled assets; if hosted, publish them through CI to an app-owned HTTPS origin and keep the allowlist or signed manifest in sync with the app release.

Complete Example

// App.tsx
import React, { Suspense, useState } from 'react';
import { Button, View, ActivityIndicator } from 'react-native';

// Lazy load heavy feature
const HeavyFeature = React.lazy(() =>
  import(/* webpackChunkName: "heavy-feature" */ './HeavyFeature')
);

const App = () => {
  const [showFeature, setShowFeature] = useState(false);
  
  return (
    <View>
      <Button 
        title="Load Feature" 
        onPress={() => setShowFeature(true)} 
      />
      
      {showFeature && (
        <Suspense fallback={<ActivityIndicator />}>
          <HeavyFeature />
        </Suspense>
      )}
    </View>
  );
};

Module Federation

Only use Module Federation when the app already has a micro-frontend architecture and the organizational boundary is worth the runtime trust boundary:

// Host app loads remote module
const RemoteModule = React.lazy(() =>
  import('remote-app/Module')
);

Federation increases the trust boundary. Keep the same first-party origin, release-manifest, code-signing, and allowlist rules as above.

Caching Strategy

import AsyncStorage from '@react-native-async-storage/async-storage';

ScriptManager.shared.setStorage(AsyncStorage);

Set storage before adding resolvers so Re.Pack can cache resolved script locator data. Return cache: false for dev server chunks or any script that should bypass caching.

When NOT to Use

Hermes Memory Mapping

Hermes reads bytecode lazily via mmap:

• Only loads executed code into memory
• No parse step needed
• Code splitting provides marginal benefit

Verification

// Check if chunk loaded correctly
ScriptManager.shared.on('loading', (script) => {
  console.log(`Loading: ${script.scriptId}`);
});

ScriptManager.shared.on('loaded', (script) => {
  console.log(`Loaded: ${script.scriptId}`);
});

ScriptManager.shared.on('error', (error) => {
  console.error('Script loading failed:', error);
});

Common Pitfalls

• Forgetting Suspense: Lazy components need fallback
• Wrong CDN path: Chunks 404 in production
• No caching: Re-downloads on every load
• Too many chunks: Network overhead exceeds savings
• Untrusted chunk source: JS chunks from third-party or user-controlled origins are equivalent to remote code execution

Related Skills

• bundle-tree-shaking.md (./bundle-tree-shaking.md) - Tree-shaking caveats
• bundle-analyze-js.md (./bundle-analyze-js.md) - Measure chunk sizes
• native-measure-tti.md (./native-measure-tti.md) - Verify TTI impact

title: Disable JS Bundle Compression
impact: HIGH
tags: android, hermes, mmap, tti, startup

Skill: Disable JS Bundle Compression

Disable Android JS bundle compression to enable Hermes memory mapping for faster startup on React Native 0.78 and earlier.

Quick Config

// android/app/build.gradle, React Native 0.78 and earlier fallback
android {
    androidResources {
        noCompress += ["bundle"]
    }
}

Note: React Native 0.79+ defaults to uncompressed Android JS bundles. Prefer checking/toggling react { enableBundleCompression = false } there instead of adding androidResources.noCompress manually.

When to Use

• Android app using Hermes
• Want faster TTI (Time to Interactive)
• Willing to trade install size for startup speed
• React Native version is 0.78 or earlier, skip otherwise (see applicability)

Background

Android compresses most files in APK/AAB by default, including index.android.bundle.

Problem: Compressed files can't be memory-mapped (mmap).

Impact: Hermes must decompress before reading, losing one of its key optimizations.

How Hermes Memory Mapping Works

Without compression:

1. Hermes opens bytecode file
2. OS memory-maps directly to disk
3. Only pages actually accessed are loaded
4. Result: Fast startup, low memory

With compression:

1. Android decompresses entire bundle
2. Loaded into memory
3. Then Hermes processes
4. Result: Slower startup, higher memory

Step-by-Step Implementation

Edit build.gradle

For React Native 0.78 and earlier, edit android/app/build.gradle:

android {
    androidResources {
        noCompress += ["bundle"]
    }
}

Full Context

android {
    namespace "com.myapp"
    defaultConfig {
        applicationId "com.myapp"
        // ...
    }
    
    androidResources {
        noCompress += ["bundle"]
    }
    
    buildTypes {
        release {
            minifyEnabled true
            // ...
        }
    }
}

Rebuild

cd android
./gradlew clean
./gradlew bundleRelease
# or
./gradlew assembleRelease

Trade-offs

Real example: 75.9 MB install → 82 MB install, but 450ms faster startup.

Applicability

React Native 0.78 and earlier: Apply this optimization manually.

React Native 0.79+: Skip this unless the project explicitly enabled bundle compression.

Verification

Check APK Contents

# Unzip APK
unzip app-release.apk -d apk-contents

# Check if bundle is compressed
file apk-contents/assets/index.android.bundle
# Should show: "data" (not "gzip compressed")

Measure TTI Impact

Use performance markers (see native-measure-tti.md (./native-measure-tti.md)) to compare before/after.

Multiple File Types

If you have other files that benefit from mmap:

androidResources {
    noCompress += ["bundle", "hbc", "data"]
}

Common Pitfalls

• Not rebuilding: Change requires clean build
• Wrong config location: Must be in android block
• Ignoring size increase: Monitor user feedback on install size
• Already default: Check if React Native version includes this

Expo Notes

For Expo projects, run npx expo prebuild first to generate android/ folder, then apply the build.gradle changes. Add android/ to version control or use a config plugin for persistent changes.

Should You Enable This?

Related Skills

• native-measure-tti.md (./native-measure-tti.md) - Measure TTI improvement
• bundle-analyze-app.md (./bundle-analyze-app.md) - Check size impact
• bundle-r8-android.md (./bundle-r8-android.md) - Offset size increase

title: Determine Library Size
impact: MEDIUM
tags: dependencies, bundlephobia, library-size

Skill: Determine Library Size

Evaluate third-party library size impact before adding to your project.

Quick Command

# Check size before installing
# Visit: https://bundlephobia.com/package/[package-name]

# Or use CLI
npx bundle-phobia-cli <package-name>

When to Use

• Evaluating new dependencies
• Comparing alternative libraries
• Auditing existing dependencies
• Investigating bundle bloat

Tools Overview

bundlephobia.com

Usage

Visit bundlephobia.com and enter package name.

Shows

• Minified size: Raw JS size
• Minified + Gzipped: Network transfer size
• Download time: Estimated on various connections
• Dependencies: What else gets pulled in
• Composition: Breakdown by dependency

Example Analysis

react-native-paper
├── Minified: 312 kB
├── Gzipped: 78 kB
└── Dependencies: 12 packages
    ├── @callstack/react-theme-provider
    ├── color
    └── ...

pkg-size.dev

Backup when bundlephobia fails.

Visit pkg-size.dev with package name.

Difference: Actually installs package in web container, may be more accurate for edge cases.

Import Cost (VS Code Extension)

Install

Search "Import Cost" in VS Code extensions or:

code --install-extension wix.vscode-import-cost

Usage

Shows inline size next to imports:

import React from 'react';           // 6.5K (gzipped)
import lodash from 'lodash';         // 71.5K (gzipped: 24.7K)
import get from 'lodash/get';        // 8K (gzipped: 2.9K)

Limitations

• Uses Webpack internally (not Metro)
• May fail on React Native-specific packages
• Doesn't account for tree shaking

Bundlephobia, pkg-size.dev, and Import Cost measure JavaScript package cost. They do not capture native code added by React Native libraries such as maps, Reanimated, Firebase, camera, video, or analytics SDKs. For native dependencies, always verify the actual IPA/AAB/APK size after installation.

Comparison Workflow

Before Adding Dependency

1. Check on bundlephobia:

   https://bundlephobia.com/package/[package-name]

2. Compare alternatives:

   moment (289 kB) vs date-fns (75 kB) vs dayjs (6 kB)

3. Check what you actually need:

   • Full library import vs specific functions
   • Native alternative available?

After Adding

1. Analyze bundle (see bundle-analyze-js.md (./bundle-analyze-js.md))
2. Verify actual impact matches expected
3. Check for duplicate dependencies

Common Large Dependencies

Quick Size Check Script

# Check size before installing
npx bundle-phobia-cli <package-name>

# Or use npm directly (less accurate)
npm pack <package-name> --dry-run 2>&1 | grep "total files"

Decision Rule

Prefer the smallest option that satisfies correctness and platform requirements, then verify the real app artifact. JS package size alone is not enough for React Native dependencies with native code.

Code Example: Optimizing Imports

// BAD: Full library
import _ from 'lodash';
_.get(obj, 'path.to.value');

// BETTER: Specific import
import get from 'lodash/get';
get(obj, 'path.to.value');

// BEST: Native JS
obj?.path?.to?.value;

Related Skills

• bundle-analyze-js.md (./bundle-analyze-js.md) - Verify actual bundle impact
• bundle-barrel-exports.md (./bundle-barrel-exports.md) - Optimize how you import
• native-sdks-over-polyfills.md (./native-sdks-over-polyfills.md) - Native alternatives to JS libs

title: Native Assets
impact: HIGH
tags: assets, images, asset-catalog, app-thinning

Skill: Native Assets

Configure platform-specific asset delivery to reduce app download size.

Quick Config

iOS Asset Catalog (Build Phase):

# Default RN template: the Xcode bundle script cd's to PROJECT_ROOT first.
export EXTRA_PACKAGER_ARGS="--asset-catalog-dest ios"

Android: Automatic via AAB — Play Store delivers correct density per device.

When to Use

• Images bloating app size
• Different device densities need different assets
• Want to leverage App Store/Play Store optimization
• Using high-resolution images

Concept: Size Suffixes

React Native convention for multiple resolutions:

assets/
├── image.jpg       # 1x resolution (base)
├── image@2x.jpg    # 2x resolution
└── image@3x.jpg    # 3x resolution

// React Native selects best one for device
<Image source={require('./assets/image.jpg')} />

Android: Automatic Optimization

Android handles this automatically.

How It Works

1. Build AAB:

   cd android && ./gradlew bundleRelease

2. Metro places images in density folders:

   android/app/build/outputs/bundle/release/
   └── base/
       └── res/
           ├── drawable-mdpi-v4/     # 1x
           ├── drawable-hdpi-v4/     # 1.5x
           ├── drawable-xhdpi-v4/    # 2x
           ├── drawable-xxhdpi-v4/   # 3x
           └── drawable-xxxhdpi-v4/  # 4x

3. Play Store delivers only needed density per device.

No configuration required for Android.

iOS: Asset Catalog Setup

iOS requires explicit configuration.

Step 1: Create Asset Catalog

Create an asset catalog in the same directory you pass to --asset-catalog-dest:

ios/RNAssets.xcassets/

React Native's bundler writes image sets into RNAssets.xcassets under the destination directory. Keep the manual command and Xcode build phase destination consistent.

Step 2: Configure Build Phase

In Xcode, add this before the React Native bundle command in the Bundle React Native code and images build phase:

export EXTRA_PACKAGER_ARGS="--asset-catalog-dest ios"

This assumes the default React Native build script, which changes directory to PROJECT_ROOT before invoking Metro. If a custom build phase runs from a different working directory, set --asset-catalog-dest relative to that working directory and verify the generated RNAssets.xcassets path.

Step 3: Build

Run build to populate asset catalog:

npx react-native run-ios --mode Release

Or manually:

npx react-native bundle \
  --entry-file index.js \
  --bundle-output ios-bundle.js \
  --platform ios \
  --dev false \
  --asset-catalog-dest ios \
  --assets-dest ios/assets

Step 4: Verify

After build, RNAssets.xcassets contains:

ios/RNAssets.xcassets/
└── assets_image_image.imageset/
    ├── Contents.json
    ├── image.jpg
    ├── image@2x.jpg
    └── image@3x.jpg

App Store then delivers only needed resolution.

Before/After Comparison

Without Asset Catalog (All Variants)

App bundle contains:
├── image.jpg       (100 KB)
├── image@2x.jpg    (300 KB)
└── image@3x.jpg    (600 KB)
Total: 1 MB

With Asset Catalog (Device-Specific)

iPhone 15 Pro receives:
└── image@3x.jpg    (600 KB)
Total: 600 KB  (40% smaller)

Asset Optimization Tips

1. Compress Images

Use tools before adding to project:

# ImageOptim (macOS)
# TinyPNG (web)
# sharp (programmatic)

npx sharp-cli input.jpg -o output.jpg --quality 80

2. Use Appropriate Formats

3. Separate Bundled Assets from Remote Images

Remote image caching libraries can help runtime image performance, but they do not reduce the size of images already bundled into the app.

Verification

iOS App Thinning Report

After export, check App Thinning Size Report.txt:

Variant: MyApp-<UUID>.ipa
Supported variant descriptors: iPhone15,2 ...
App size: 3.5 MB compressed, 10.6 MB uncompressed

Use Emerge Tools

Upload IPA to see asset breakdown.

Common Pitfalls

• Inconsistent destination paths: The build phase and manual bundle command should point at the same asset catalog parent directory
• Missing build phase config: Assets not processed
• Not using size suffixes: All variants included anyway
• Forgetting to rebuild: Changes need fresh build

Future Note

As of the March 2026 book export, iOS asset catalog generation is not described as default. Verify current React Native release notes before applying this manually.

Related Skills

• bundle-analyze-app.md (./bundle-analyze-app.md) - Verify asset impact
• bundle-r8-android.md (./bundle-r8-android.md) - Android code optimization

title: R8 Code Shrinking
impact: HIGH
tags: android, r8, proguard, minify, shrink

Skill: R8 Code Shrinking

Enable R8 for Android to shrink, optimize, and obfuscate native code.

Quick Config

// android/app/build.gradle
def enableProguardInReleaseBuilds = true

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
        }
    }
}

When to Use

• Android app size too large
• Want basic obfuscation to raise reverse-engineering effort, not as a security boundary
• Building release APK/AAB

What is R8?

R8 replaces ProGuard in Android:

• Shrinks: Removes unused code
• Optimizes: Improves bytecode
• Obfuscates: Renames classes/methods

Compatibility: Uses ProGuard configuration format.

Step-by-Step Instructions

1. Enable R8

Edit android/app/build.gradle:

def enableProguardInReleaseBuilds = true

This sets minifyEnabled = true for release builds.

2. Enable Resource Shrinking (Optional)

Further reduces size by removing unused resources:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true  // Requires minifyEnabled
            
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

For Expo projects, wire release minification through android.enableMinifyInReleaseBuilds and resource shrinking through android.enableShrinkResourcesInReleaseBuilds. In managed/prebuild projects, set these through expo-build-properties so they survive expo prebuild.

3. Configure ProGuard Rules (If Needed)

Edit android/app/proguard-rules.pro. React Native defaults are usually sufficient—only add rules when specific libraries break after enabling R8.

Only add if using Firebase (@react-native-firebase/*):

-keep class io.invertase.firebase.** { *; }
-dontwarn io.invertase.firebase.**

Only add if using Retrofit:

-keepattributes Signature
-keepattributes *Annotation*
-keep class retrofit2.** { *; }
-dontwarn retrofit2.**

See Common Library Rules (#common-library-rules) and Troubleshooting (#troubleshooting) for more examples.

4. Build and Test

cd android
./gradlew assembleRelease
# or
./gradlew bundleRelease

Critical: Test thoroughly! R8 can remove code it thinks is unused.

ProGuard Rules Reference

Keep Entire Package

-keep class com.mypackage.** { *; }

Keep Classes with Annotation

-keep @interface com.facebook.proguard.annotations.DoNotStrip
-keep @com.facebook.proguard.annotations.DoNotStrip class *
-keepclassmembers class * {
    @com.facebook.proguard.annotations.DoNotStrip *;
}

Disable Obfuscation (If Needed)

# proguard-rules.pro
-dontobfuscate

Use when:

• Debugging crashes (stack traces more readable)
• Library requires class names

Size Impact

Example from guide:

• Without R8: 9.5 MB
• With R8: 6.3 MB
• Savings: 33%

Larger apps may see 20-30% reduction.

Troubleshooting

App Crashes After R8

Usually means needed class was removed.

Debug steps:

1. Check crash log for class name
2. Add keep rule:

   -keep class com.example.CrashedClass { *; }

3. Rebuild and test

Library Specific Rules

Many libraries provide ProGuard rules. Check:

• Library README
• Library's consumer-proguard-rules.pro
• Stack Overflow for library + proguard

Common Library Rules

# Hermes (usually auto-included)
-keep class com.facebook.hermes.unicode.** { *; }

# React Native
-keep class com.facebook.react.** { *; }

# Gson
-keepattributes Signature
-keep class com.google.gson.** { *; }

# OkHttp
-dontwarn okhttp3.**
-dontwarn okio.**

Verification

Check APK Size

# Build
./gradlew assembleRelease

# Check size
ls -la android/app/build/outputs/apk/release/

Use Ruler for Detailed Analysis

See bundle-analyze-app.md (./bundle-analyze-app.md).

Verify Obfuscation

Decompile APK to check class names are obfuscated:

# Using jadx or similar
jadx android/app/build/outputs/apk/release/app-release.apk

Verify Runtime Behavior

Use agent-device to install or open the release build, navigate critical flows, capture snapshots/screenshots, and collect logs. If it is missing and release verification is needed, install it through the environment's approved/trusted path or ask the user to install or enable it. Read the agent-device skill or CLI help when available before writing exact commands.

Common Pitfalls

• Not testing release build: Always QA with R8 enabled
• Missing library rules: Check library docs
• Over-keeping: Too many keep rules negates benefits
• Reflection: Code using reflection may break

Related Skills

• bundle-analyze-app.md (./bundle-analyze-app.md) - Measure size impact
• bundle-native-assets.md (./bundle-native-assets.md) - Further size reduction

title: Tree Shaking
impact: HIGH
tags: bundle, tree-shaking, dead-code, metro, repack

Skill: Tree Shaking

Enable dead code elimination to remove unused exports from your JavaScript bundle.

Quick Config

# .env (Expo SDK 52+)
EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
EXPO_UNSTABLE_TREE_SHAKING=1

// metro.config.js
config.transformer.getTransformOptions = async () => ({
  transform: { experimentalImportSupport: true },
});

// babel.config.js (non-Expo projects must set `disableImportExportTransform`)
module.exports = {
  presets: [
    [
      'module:@react-native/babel-preset',
      { disableImportExportTransform: true },
    ],
  ],
};

When to Use

• Bundle includes unused library code
• Want automatic barrel export optimization
• Using Expo SDK 52+ (recommended approach)
• Project already uses Re.Pack (@callstack/repack)

Platform Support

Setup: Expo SDK 52+

1. Enable Import Support

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

config.transformer.getTransformOptions = async () => ({
  transform: {
    experimentalImportSupport: true,
  },
});

module.exports = config;

2. Enable Tree Shaking

Create/edit .env:

EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
EXPO_UNSTABLE_TREE_SHAKING=1

Note: Only applies in production builds.

Setup: Metro with ESBuild

npm install @rnx-kit/metro-serializer-esbuild

Configure in metro.config.js.

Setup: Re.Pack (Only If Already Installed)

Important: Re.Pack (@callstack/repack) is a custom bundler using Rspack/Webpack. Only apply these instructions if the project already has Re.Pack configured. Do not suggest migrating a codebase to Re.Pack—it's rarely necessary and requires significant setup.

If project has @callstack/repack in dependencies:

Tree shaking is enabled by default with Rspack. Verify in config:

// rspack.config.js or webpack.config.js
module.exports = {
  optimization: {
    usedExports: true, // Mark unused exports
    minimize: true, // Remove during minification
  },
};

Platform Shaking

Code inside Platform.OS and Platform.select checks is removed for other platforms:

// IMPORTANT: import Platform directly from 'react-native'
import { Platform } from 'react-native';

if (Platform.OS === 'ios') {
  // Removed from Android bundle
}

if (Platform.select({ ios: true, android: false }) === 'ios') {
  // Removed from Android bundle
}

Critical: Must use direct import. This does NOT work:

import * as RN from 'react-native';
if (RN.Platform.OS === 'ios') {
  // NOT removed - optimization fails
}

For non-Expo projects, requires both experimentalImportSupport: true in Metro config and disableImportExportTransform: true in Babel config.

Impact: Savings from enabling platform shaking on a bare React Native Community CLI project are:

• 5% smaller Hermes bytecode (2.79 MB → 2.64 MB)
• 15% smaller minified JS bundle (1 MB → 0.85 MB)

Requirements for Tree Shaking

ESM Imports Required

// ✅ ESM - Tree shakeable
import { foo } from './module';

// ❌ CommonJS - Not tree shakeable
const { foo } = require('./module');

Side Effects Declaration

Libraries must declare side-effect-free in package.json:

{
  "sideEffects": false
}

Or specify files with side effects:

{
  "sideEffects": ["*.css", "./src/polyfills.js"]
}

Size Impact

Expected improvement: 10-15% bundle size reduction.

Verification

1. Build production bundle (see bundle-analyze-js.md (./bundle-analyze-js.md))
2. Analyze with source-map-explorer (see bundle-analyze-js.md (./bundle-analyze-js.md))
3. Search for functions you know are unused
4. If found → tree shaking not working

Test Example

// test-treeshake.js
export const usedFunction = () => 'used';
export const unusedFunction = () => 'unused'; // Should be removed

// app.js
import { usedFunction } from './test-treeshake';

After building, search bundle for unusedFunction. Should not exist.

Common Pitfalls

• Not using production build: Tree shaking only in prod
• CommonJS modules: Need ESM for full effectiveness
• Side effects not declared: Library may not be shakeable
• Dynamic imports: require(variable) prevents analysis
• Babel/Metro config mismatch: disableImportExportTransform must match experimentalImportSupport

Related Skills

• bundle-analyze-js.md (./bundle-analyze-js.md) - Verify tree shaking effect
• bundle-barrel-exports.md (./bundle-barrel-exports.md) - Manual alternative
• bundle-code-splitting.md (./bundle-code-splitting.md) - Remote chunk loading safeguards

title: High-Performance Animations
impact: MEDIUM
tags: reanimated, animations, worklets, ui-thread

Skill: High-Performance Animations

Use React Native Reanimated for smooth 60+ FPS animations.

Quick Pattern

Incorrect (JS thread - blocks on heavy work):

const opacity = useRef(new Animated.Value(0)).current;
Animated.timing(opacity, { toValue: 1 }).start();

Correct (UI thread - smooth even during JS work):

const opacity = useSharedValue(0);
const style = useAnimatedStyle(() => ({ opacity: opacity.value }));
opacity.value = withTiming(1);

When to Use

• Animations drop frames or feel janky
• UI freezes during animations
• Need gesture-driven animations
• Want animations to run during heavy JS work

Prerequisites

• react-native-reanimated (v4+) and react-native-worklets installed

npm install react-native-reanimated react-native-worklets

Add to babel.config.js:

module.exports = {
  plugins: ['react-native-worklets/plugin'],  // Must be last
};

Note: Reanimated 4 requires React Native's New Architecture (Fabric + TurboModules). The Legacy Architecture is no longer supported. If upgrading from v3, see the migration notes at the end of this document.

Key Concepts

Main Thread vs JS Thread

• Main/UI Thread: Handles native rendering (60+ FPS target)
• JS Thread: Runs React and your JavaScript

Problem: Heavy JS work blocks animations running on JS thread.

Solution: Run animations on UI thread with Reanimated worklets.

Step-by-Step Instructions

1. Basic Animated Style (UI Thread)

import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming
} from 'react-native-reanimated';

const FadeInView = () => {
  const opacity = useSharedValue(0);

  // This runs on UI thread - won't be blocked by JS
  const animatedStyle = useAnimatedStyle(() => {
    return { opacity: opacity.value };
  });

  useEffect(() => {
    opacity.value = withTiming(1, { duration: 500 });
  }, []);

  return <Animated.View style={[styles.box, animatedStyle]} />;
};

2. Run Code on UI Thread with scheduleOnUI

import { scheduleOnUI } from 'react-native-worklets';

const triggerAnimation = () => {
  scheduleOnUI(() => {
    'worklet';
    console.log('Running on UI thread');
    // Direct UI manipulations here
  });
};

3. Call JS from UI Thread with scheduleOnRN

import { scheduleOnRN } from 'react-native-worklets';
import { Pressable } from 'react-native';
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withTiming,
} from 'react-native-reanimated';

// Regular JS function
const trackAnalytics = (value) => {
  analytics.track('animation_complete', { value });
};

const AnimatedComponent = () => {
  const progress = useSharedValue(0);

  const handlePress = () => {
    progress.value = withTiming(1, { duration: 200 }, (finished) => {
      if (finished) {
        scheduleOnRN(trackAnalytics, 1);
      }
    });
  };

  const animatedStyle = useAnimatedStyle(() => {
    return { opacity: progress.value };
  });

  return (
    <Pressable onPress={handlePress}>
      <Animated.View style={animatedStyle} />
    </Pressable>
  );
};

Avoid calling scheduleOnRN from useAnimatedStyle; style worklets can evaluate more often than an analytics or state callback should run. Prefer animation completion callbacks or useAnimatedReaction.

4. Animation with Callback

import { scheduleOnRN } from 'react-native-worklets';

const AnimatedButton = () => {
  const scale = useSharedValue(1);

  const onComplete = () => {
    console.log('Animation finished!');
  };

  const handlePress = () => {
    scale.value = withTiming(
      1.2,
      { duration: 200 },
      (finished) => {
        if (finished) {
          scheduleOnRN(onComplete);
        }
      }
    );
  };

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ scale: scale.value }],
  }));

  return (
    <Pressable onPress={handlePress}>
      <Animated.View style={[styles.button, animatedStyle]}>
        <Text>Press Me</Text>
      </Animated.View>
    </Pressable>
  );
};

When to Use What

For React Native Web targets, CSS transitions can be appropriate for simple state-driven style changes. In native apps, keep shared values/worklets for gesture-driven, scroll-driven, layout-sensitive, or orchestrated animations.

Common Pitfalls

• Accessing React state in worklets: Use useSharedValue instead of useState for animated values
• Not using Animated components: Must use Animated.View, Animated.Text, etc.
• Heavy computation in useAnimatedStyle: Keep worklets fast
• Forgetting 'worklet' directive: Required for inline worklet functions

// BAD: Regular function in useAnimatedStyle
const style = useAnimatedStyle(() => {
  heavyComputation();  // Blocks UI thread!
  return { opacity: 1 };
});

// GOOD: Keep worklets fast
const style = useAnimatedStyle(() => {
  return { opacity: opacity.value };  // Just read value
});

Migrating from Reanimated 3.x to 4.x

If you're upgrading from Reanimated 3.x, here are the key changes.

Can't upgrade to v4? If your project is blocked from migrating to New Architecture (e.g., incompatible native libraries, complex native code, or timeline constraints), keep using existing APIs and leverage native drivers where applicable. Avoid introducing legacy Reanimated 3.x or older to reduce future migration complexity.

Breaking Changes

Removed APIs

• useAnimatedGestureHandler - Migrate to the Gesture API from react-native-gesture-handler v2+
• addWhitelistedNativeProps / addWhitelistedUIProps - No longer needed
• combineTransition - Use EntryExitTransition.entering(...).exiting(...) instead

withSpring Changes

// Before (v3)
withSpring(value, {
  restDisplacementThreshold: 0.01,
  restSpeedThreshold: 0.01,
  duration: 300,
});

// After (v4)
withSpring(value, {
  energyThreshold: 0.01,  // Replaces both threshold parameters
  duration: 200,          // Duration is now "perceptual" (~1.5x actual time)
});

Migration Checklist

1. Enable New Architecture - Reanimated 4 only supports Fabric + TurboModules
2. Install react-native-worklets - Required new dependency
3. Update Babel plugin - Change 'react-native-reanimated/plugin' to 'react-native-worklets/plugin'
4. Update imports - Move worklet functions to react-native-worklets
5. Update API calls - New functions take callback + args directly (not curried)
6. Rebuild native apps - Required after adding react-native-worklets

Related Skills

• js-measure-fps.md (./js-measure-fps.md) - Verify animation frame rate
• js-bottomsheet.md (./js-bottomsheet.md) - Keep bottom sheet visual state on the UI thread
• js-concurrent-react.md (./js-concurrent-react.md) - React-level deferral with useTransition

title: Atomic State Management
impact: HIGH
tags: state, jotai, zustand, re-renders, context

Skill: Atomic State Management

Use atomic state libraries (Jotai, Zustand) to reduce unnecessary re-renders without manual memoization.

Quick Pattern

Before (broad Context value):

const { filter, todos } = useContext(TodoContext);
// Re-renders when the provider value identity changes

After (Zustand - only subscribed state):

const filter = useTodoStore((s) => s.filter);
// Only re-renders when filter changes

When to Use

• Global state changes cause widespread re-renders
• Using React Context for app state
• Components re-render even when their data hasn't changed
• Want to avoid manual useMemo/useCallback everywhere
• Not ready to adopt React Compiler

Prerequisites

• State management library: jotai or zustand

npm install jotai
# or
npm install zustand

Problem Description

Context is not inherently slow, but a broad provider value makes every consumer of that context eligible to re-render when the value identity changes. Atomic stores help when profiling shows unrelated subscribers rendering after global state updates.

Step-by-Step Instructions

Using Jotai

1. Define Atoms

import { atom } from 'jotai';

// Each atom is an independent piece of state
const filterAtom = atom('all');
const todosAtom = atom([]);

// Derived atom (computed value)
const filteredTodosAtom = atom((get) => {
  const filter = get(filterAtom);
  const todos = get(todosAtom);
  
  if (filter === 'active') return todos.filter(t => !t.completed);
  if (filter === 'completed') return todos.filter(t => t.completed);
  return todos;
});

2. Use Atoms in Components

import { useAtom, useAtomValue, useSetAtom } from 'jotai';

// Only re-renders when filterAtom changes
const FilterMenu = () => {
  const [filter, setFilter] = useAtom(filterAtom);
  
  return (
    <View>
      {['all', 'active', 'completed'].map((f) => (
        <Pressable key={f} onPress={() => setFilter(f)}>
          <Text style={filter === f ? styles.active : null}>{f}</Text>
        </Pressable>
      ))}
    </View>
  );
};

// Only re-renders when todosAtom changes
const TodoItem = ({ id }) => {
  const setTodos = useSetAtom(todosAtom);  // Only setter, no re-render on read
  
  const toggleTodo = () => {
    setTodos((prev) => 
      prev.map((t) => t.id === id ? { ...t, completed: !t.completed } : t)
    );
  };
  
  return <Pressable onPress={toggleTodo}>...</Pressable>;
};

Using Zustand

1. Create Store

import { create } from 'zustand';

const useTodoStore = create((set, get) => ({
  filter: 'all',
  todos: [],
  
  setFilter: (filter) => set({ filter }),
  
  toggleTodo: (id) => set((state) => ({
    todos: state.todos.map((t) =>
      t.id === id ? { ...t, completed: !t.completed } : t
    ),
  })),
  
  // Selector for derived state
  getFilteredTodos: () => {
    const { filter, todos } = get();
    if (filter === 'active') return todos.filter(t => !t.completed);
    if (filter === 'completed') return todos.filter(t => t.completed);
    return todos;
  },
}));

2. Use Selectors

// Only re-renders when filter changes
const FilterMenu = () => {
  const filter = useTodoStore((state) => state.filter);
  const setFilter = useTodoStore((state) => state.setFilter);
  
  return (
    <View>
      {['all', 'active', 'completed'].map((f) => (
        <Pressable key={f} onPress={() => setFilter(f)}>
          <Text>{f}</Text>
        </Pressable>
      ))}
    </View>
  );
};

// Only re-renders when todos change
const TodoList = () => {
  const todos = useTodoStore((state) => state.todos);
  return todos.map((todo) => <TodoItem key={todo.id} {...todo} />);
};

Comparison

When to Use Which

Do not migrate global state solely for fewer re-renders if React Compiler or narrower subscriptions solve the measured issue. Atomic state helps when broad Context/store updates cause unrelated subscribers to render.

• Jotai: Fine-grained state, many small atoms, derived/async atoms
• Zustand: Simpler mental model, single store, familiar Redux-like pattern
• React Compiler: If available, may eliminate need for these libraries

Common Pitfalls

• Over-atomizing: Don't create an atom for every variable. Group related state.
• Missing selectors in Zustand: Always use selectors to prevent unnecessary re-renders.
• Derived state without memoization: Use derived atoms (Jotai) or memoized selectors.

Related Skills

• js-bottomsheet.md (./js-bottomsheet.md) - Avoid context-driven bottom sheet subtree re-renders
• js-react-compiler.md (./js-react-compiler.md) - Automatic memoization alternative
• js-profile-react.md (./js-profile-react.md) - Verify re-render reduction

title: Bottom Sheet
impact: HIGH
tags: bottom-sheet, gorhom, re-renders, shared-values, gestures, context, scrollable, modal, keyboard

Skill: Bottom Sheet Best Practices

Optimize @gorhom/bottom-sheet for smooth 60 FPS by keeping gesture/scroll-driven state on the UI thread.

Quick Pattern

Incorrect (can re-enter JS repeatedly during interaction — full subtree re-render):

const handleAnimate = useCallback((fromIndex, toIndex) => {
  setIsExpanded(toIndex > 0); // re-renders entire tree
}, []);

<BottomSheet onAnimate={handleAnimate}>
  <ExpensiveContent isExpanded={isExpanded} />
</BottomSheet>

Correct (stays on UI thread — zero re-renders):

const animatedIndex = useSharedValue(0);

const overlayStyle = useAnimatedStyle(() => ({
  opacity: interpolate(
    animatedIndex.value,
    [0, 1],
    [0, 0.5],
    Extrapolation.CLAMP
  ),
}));

<BottomSheet animatedIndex={animatedIndex}>
  <ExpensiveContent />
</BottomSheet>
<Animated.View style={[styles.overlay, overlayStyle]} />

When to Use

• Implementing or optimizing a bottom sheet with @gorhom/bottom-sheet
• Bottom sheet gestures cause jank or dropped frames
• Scroll inside bottom sheet triggers excessive re-renders
• Context provider wrapping bottom sheet re-renders the entire subtree
• Visual-only state (shadow, opacity, footer visibility) managed with useState
• Need to choose between BottomSheet and BottomSheetModal
• Scrollable content inside bottom sheet doesn't coordinate with gestures
• Keyboard doesn't interact properly with the sheet

Prerequisites

• Check the official @gorhom/bottom-sheet versioning / compatibility table first.
• If your app is on @gorhom/bottom-sheet below v5, upgrade to v5 before applying the patterns in this skill.
• @gorhom/bottom-sheet v5 is the current maintained line and is built for react-native-reanimated v3.
• react-native-reanimated v4 may work in some apps, but the bottom-sheet docs do not officially guarantee it. Decide explicitly whether to stay on v3 or try v4 and validate thoroughly on device.
• react-native-gesture-handler v2+

npm install @gorhom/bottom-sheet@^5 react-native-reanimated@^3 react-native-gesture-handler

Note: In v5, enableDynamicSizing defaults to true. If you need fixed snap-point indexing or do not want the library to insert a dynamic snap point based on content height, set enableDynamicSizing={false} explicitly.

Problem Description

Bottom-sheet gesture, animation, and scroll callbacks that update React state can re-render the sheet subtree during interaction. In practice, callbacks like onAnimate may run repeatedly as the sheet retargets animations, which can cause visible jank if they drive expensive React updates.

Step-by-Step Instructions

1. Convert Gesture-Driven State to SharedValue

Avoid React state for gesture-driven visual state. Update a shared value and consume it via useAnimatedStyle.

Before:

const [shadowOpacity, setShadowOpacity] = useState(0);

const handleAnimate = useCallback((fromIndex, toIndex) => {
  setShadowOpacity(toIndex > 0 ? 0.3 : 0);
}, []);

<BottomSheet onAnimate={handleAnimate}>
  <View style={{ shadowOpacity }}>
    <HeavyContent />
  </View>
</BottomSheet>

After:

const animatedIndex = useSharedValue(0);

const shadowStyle = useAnimatedStyle(() => ({
  shadowOpacity: interpolate(
    animatedIndex.value,
    [0, 1],
    [0, 0.3],
    Extrapolation.CLAMP
  ),
}));

<BottomSheet animatedIndex={animatedIndex}>
  <Animated.View style={shadowStyle}>
    <HeavyContent />
  </Animated.View>
</BottomSheet>

2. Drive Sheet-Index Visibility via useAnimatedReaction

Toggling content based on sheet index via {showFooter && <Footer/>} causes mount/unmount cycles on every snap. Instead, always mount, animate visibility from animatedIndex, and bridge only the minimal boolean needed for pointerEvents/accessibility — scoped to a wrapper so the full tree doesn't re-render.

Before:

const [showFooter, setShowFooter] = useState(false);

// re-mounts footer on every toggle
{showFooter && <Footer />}

After:

const SheetVisibilityWrapper = ({ animatedIndex, threshold = 1, children }) => {
  const [isInteractive, setIsInteractive] = useState(false);

  const style = useAnimatedStyle(() => {
    const progress = interpolate(
      animatedIndex.value,
      [threshold - 0.01, threshold],
      [0, 1],
      Extrapolation.CLAMP
    );

    return {
      opacity: progress,
      transform: [{ translateY: interpolate(progress, [0, 1], [50, 0]) }],
    };
  });

  useAnimatedReaction(
    () => animatedIndex.value >= threshold,
    (visible, prev) => {
      if (visible !== prev) runOnJS(setIsInteractive)(visible);
    }
  );

  return (
    <Animated.View
      style={style}
      pointerEvents={isInteractive ? 'auto' : 'none'}
      accessibilityElementsHidden={!isInteractive}
      importantForAccessibility={isInteractive ? 'auto' : 'no-hide-descendants'}
    >
      {children}
    </Animated.View>
  );
};

// Usage:
<SheetVisibilityWrapper animatedIndex={animatedIndex}>
  <Footer />
</SheetVisibilityWrapper>

3. Keep Scroll-Driven Logic off the JS Thread

BottomSheetScrollView ignores scrollEventThrottle, so setting it is not an optimization. Keep JS onScroll work minimal, or move scroll-driven logic to useAnimatedScrollHandler (see js-animations-reanimated.md (./js-animations-reanimated.md)) so it stays on the UI thread:

const scrollHandler = useAnimatedScrollHandler((event) => {
  scrollY.value = event.contentOffset.y;
});

<BottomSheetScrollView onScroll={scrollHandler}>
  <Content />
</BottomSheetScrollView>

4. Use Library-Provided Components and Props

Scrollables — always use these instead of React Native built-ins inside a bottom sheet:

import {
  BottomSheetScrollView,
  BottomSheetFlatList,
  BottomSheetSectionList,
} from '@gorhom/bottom-sheet';

// FlashList v2: BottomSheetFlashList is deprecated.
// Create the scroll component, then pass it to FlashList.
import { useBottomSheetScrollableCreator } from '@gorhom/bottom-sheet';
import { FlashList } from '@shopify/flash-list';

const BottomSheetFlashListScrollComponent = useBottomSheetScrollableCreator();

<BottomSheet snapPoints={snapPoints} enableDynamicSizing={false}>
  <FlashList
    data={data}
    keyExtractor={(item) => item.id}
    renderItem={renderItem}
    renderScrollComponent={BottomSheetFlashListScrollComponent}
  />
</BottomSheet>

Key props:

5. BottomSheetModal Setup

import {
  BottomSheetModal,
  BottomSheetModalProvider,
} from '@gorhom/bottom-sheet';

const App = () => (
  <BottomSheetModalProvider>
    <BottomSheetModal
      ref={modalRef}
      snapPoints={snapPoints}
      enableDismissOnClose={true}
    >
      <Content />
    </BottomSheetModal>
  </BottomSheetModalProvider>
);

iOS layering fix — use FullWindowOverlay to render above native navigation:

import { FullWindowOverlay } from 'react-native-screens';

<BottomSheetModal
  containerComponent={(props) => <FullWindowOverlay>{props.children}</FullWindowOverlay>}
>

6. Keyboard Handling

<BottomSheet
  snapPoints={snapPoints}
  enableDynamicSizing={false}
  keyboardBehavior="interactive"    // 'extend' | 'fillParent' | 'interactive'
  keyboardBlurBehavior="restore"    // reset sheet position when keyboard dismisses
  enableBlurKeyboardOnGesture={true} // dismiss keyboard on drag
>
  <BottomSheetTextInput
    placeholder="Type here..."
    style={styles.input}
  />
</BottomSheet>

Prefer BottomSheetTextInput inside a bottom sheet. If you need a custom input, copy the focus/blur handlers from the library's BottomSheetTextInput implementation so keyboard handling still works correctly.

Derived Animations with animatedPosition

Use the animatedPosition shared value for smooth derived UI that stays on the UI thread:

const animatedPosition = useSharedValue(0);

const backdropStyle = useAnimatedStyle(() => ({
  opacity: interpolate(
    animatedPosition.value,
    [0, 300],
    [0.5, 0],
    Extrapolation.CLAMP
  ),
}));

<BottomSheet animatedPosition={animatedPosition} snapPoints={snapPoints}>
  <Content />
</BottomSheet>
<Animated.View style={[StyleSheet.absoluteFill, backdropStyle]} pointerEvents="none" />

Native Alternative: react-native-true-sheet

If your app already runs on New Architecture (Fabric) and needs a standard native-feeling sheet, evaluate @lodev09/react-native-true-sheet. Keep @gorhom/bottom-sheet when you need fine-grained Reanimated customization, custom gestures, or a mature cross-platform fallback.

npm install @lodev09/react-native-true-sheet

Common Pitfalls

• Using onChange for continuous position tracking — it fires on snap completion only (discrete). Use animatedPosition or animatedIndex shared values instead.
• Starting timing animations inside sheet-index style worklets — derive gesture-linked visuals with interpolate; reserve withTiming for explicit state transitions.
• Forgetting pointerEvents='none' on always-mounted hidden elements — invisible elements still capture touches.
• Missing accessibility attributes on hidden elements — add accessibilityElementsHidden and importantForAccessibility='no-hide-descendants'.
• Bundling independent state values in one context — see js-atomic-state.md (./js-atomic-state.md) for splitting patterns.
• Assuming enableDynamicSizing must be disabled whenever you pass snapPoints — it does not have to be, but leaving it enabled can insert an additional snap point and change indexing.
• Using React Native ScrollView/FlatList inside bottom sheet — gestures won't coordinate. Use BottomSheetScrollView, BottomSheetFlatList, etc.
• Gesture conflicts with React Native touchables — when touches do not respond inside the sheet, use the touchable components exported by @gorhom/bottom-sheet, especially on Android.
• Not providing containerHeight — causes an extra re-render on mount for measurement.
• Using a custom TextInput without porting the library's focus/blur handlers — keyboard handling will be incomplete. Prefer BottomSheetTextInput unless you need a custom input.

Related Skills

• js-animations-reanimated.md (./js-animations-reanimated.md) — SharedValue and useAnimatedStyle fundamentals
• js-atomic-state.md (./js-atomic-state.md) — Context splitting and atomic state patterns
• js-profile-react.md (./js-profile-react.md) — Profiling to measure re-render reduction
• js-measure-fps.md (./js-measure-fps.md) — Verify FPS improvement after optimization

title: Concurrent React
impact: HIGH
tags: useDeferredValue, useTransition, suspense, concurrent

Skill: Concurrent React

Use useDeferredValue and useTransition to improve perceived performance by prioritizing critical updates.

Quick Pattern

Incorrect (blocks input on every keystroke):

const [query, setQuery] = useState('');
<TextInput value={query} onChangeText={setQuery} />
<ExpensiveList query={query} />  // Blocks typing

Correct (input stays responsive):

const [query, setQuery] = useState('');
const deferredQuery = useDeferredValue(query);
<TextInput value={query} onChangeText={setQuery} />
<ExpensiveList query={deferredQuery} />  // Deferred update

When to Use

• Search/filter inputs feel laggy with large result sets
• Expensive computations block UI interactions
• Loading states appear too frequently
• Want to show stale content while loading new content
• Need to prioritize user input over background updates

Prerequisites

• React 18+ features (useDeferredValue, useTransition, Suspense)
• React Native version that supports your target concurrent behavior; validate on the app architecture you ship

Concept Overview

Concurrent React allows updates to be:

• Paused: Low-priority work can wait
• Interrupted: User input takes priority
• Abandoned: Outdated updates can be skipped

Step-by-Step Instructions

Pattern 1: Defer Expensive Rendering with useDeferredValue

Use when a value drives expensive computation but you want input to stay responsive.

import { useState, useDeferredValue } from 'react';

const SearchScreen = () => {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  
  // query updates immediately (input stays responsive)
  // deferredQuery updates when React has time
  
  return (
    <View>
      <TextInput
        value={query}
        onChangeText={setQuery}
        placeholder="Search..."
      />
      {/* ExpensiveList receives deferred value */}
      <ExpensiveList query={deferredQuery} />
    </View>
  );
};

Pattern 2: Show Stale Content While Loading

const SearchWithStaleIndicator = () => {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;
  
  return (
    <View>
      <TextInput value={query} onChangeText={setQuery} />
      <View style={isStale && { opacity: 0.7 }}>
        <SearchResults query={deferredQuery} />
      </View>
      {isStale && <ActivityIndicator />}
    </View>
  );
};

Pattern 3: Transition Non-Critical Updates with useTransition

Use when you have multiple state updates and want to mark some as low-priority.

import { useState, useTransition } from 'react';

const TransitionExample = () => {
  const [count, setCount] = useState(0);
  const [heavyData, setHeavyData] = useState(null);
  const [isPending, startTransition] = useTransition();
  
  const handleIncrement = () => {
    // High priority - updates immediately
    setCount(c => c + 1);
    
    // Low priority - can be interrupted
    startTransition(() => {
      setHeavyData(computeExpensiveData());
    });
  };
  
  return (
    <View>
      <Text>Count: {count}</Text>
      {isPending ? <ActivityIndicator /> : <HeavyComponent data={heavyData} />}
      <Button onPress={handleIncrement} title="Increment" />
    </View>
  );
};

Pattern 4: Suspense for Data Fetching

Use this only with a Suspense-enabled data source or framework integration. Wrapping arbitrary fetch() code in Suspense does not make it suspend automatically.

import { Suspense, useDeferredValue } from 'react';

const DataScreen = () => {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  
  return (
    <View>
      <TextInput value={query} onChangeText={setQuery} />
      <Suspense fallback={<LoadingSpinner />}>
        <SearchResults query={deferredQuery} />
      </Suspense>
    </View>
  );
};

Code Examples

Slow Component Optimization

// Without Concurrent React - UI freezes
const SlowSearch = () => {
  const [query, setQuery] = useState('');
  
  return (
    <>
      <TextInput value={query} onChangeText={setQuery} />
      <SlowComponent query={query} /> {/* Blocks every keystroke */}
    </>
  );
};

// With Concurrent React - UI stays responsive  
const FastSearch = () => {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  
  return (
    <>
      <TextInput value={query} onChangeText={setQuery} />
      <SlowComponent query={deferredQuery} />
    </>
  );
};

// Important: Wrap SlowComponent in memo to prevent re-renders from parent
const SlowComponent = memo(({ query }) => {
  // Expensive computation here
});

Automatic Batching (React 18+)

React 18 automatically batches state updates:

// Before React 18 - 2 re-renders
setTimeout(() => {
  setCount(c => c + 1);
  setFlag(f => !f);
  // Rendered twice
}, 1000);

// React 18+ - 1 re-render (automatic batching)
setTimeout(() => {
  setCount(c => c + 1);
  setFlag(f => !f);
  // Rendered once!
}, 1000);

When to Use Which

Important Considerations

1. Wrap expensive components in memo(): Without memoization, the component re-renders from parent anyway.

2. Validate on your shipped architecture: Concurrent behavior depends on the React Native and React versions in the app.

3. Don't overuse: Only defer truly expensive work. Adding complexity for fast components is counterproductive.

Common Pitfalls

• Forgetting subtree isolation: useDeferredValue helps most when the expensive subtree is memoized or otherwise isolated from immediate parent re-renders
• Using for simple state: Overhead isn't worth it for cheap updates
• Expecting faster computation: These hooks don't make code faster, they prioritize what runs when

Related Skills

• js-profile-react.md (./js-profile-react.md) - Identify slow components
• js-react-compiler.md (./js-react-compiler.md) - Automatic memoization
• js-lists-flatlist-flashlist.md (./js-lists-flatlist-flashlist.md) - For list-specific optimizations

title: Higher-Order Lists
impact: CRITICAL
tags: lists, flatlist, flashlist, legend-list, scrollview, virtualization

Skill: Higher-Order Lists

Replace ScrollView with FlatList, FlashList, or Legend List for performant large list rendering.

Quick Pattern

Incorrect:

<ScrollView>
  {items.map((item) => <Item key={item.id} {...item} />)}
</ScrollView>

Correct:

<FlashList
  data={items}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <Item {...item} />}
  // FlashList v1 only: add estimatedItemSize.
  // FlashList v2+: do not add estimated sizing props.
/>

When to Use

• Rendering enough items that eager mounting affects FPS, memory, or startup
• List scrolling is choppy or laggy
• App freezes when loading list data
• Memory usage spikes with long lists

Prerequisites

• @shopify/flash-list for FlashList on React Native New Architecture
• @legendapp/list for a JS/TypeScript list option without native dependencies
• Understanding of list virtualization

Version Guardrail

• FlashList v1: estimatedItemSize is part of the optimization guidance.
• FlashList v2 and newer: estimatedItemSize, estimatedListSize, and estimatedFirstItemOffset are deprecated and no longer used. Do not flag them as missing.
• Before suggesting a FlashList fix, confirm the installed major version and tailor the advice. See FlashList v2 changes.

Step-by-Step Instructions

1. Identify the Problem

FPS Drop Graph (images/fps-drop-graph.png)

// BAD: ScrollView renders ALL items at once
const BadList = ({ items }) => (
  <ScrollView>
    {items.map((item) => (
      <View key={item.id}>
        <Text>{item.title}</Text>
      </View>
    ))}
  </ScrollView>
);

Large eager lists mount every row immediately, increasing JS work, native view count, and memory before the user can interact.

2. Replace with FlatList

import { FlatList } from 'react-native';

const BetterList = ({ items }) => {
  const renderItem = ({ item }) => (
    <View>
      <Text>{item.title}</Text>
    </View>
  );
  
  return (
    <FlatList
      data={items}
      renderItem={renderItem}
      keyExtractor={(item) => item.id}
    />
  );
};