Expo Ecosystem Reference

Managed vs Bare Workflow

Managed workflow (recommended): Use app.json/app.config.ts to configure native projects. Run npx expo prebuild to generate ios/ and android/ directories from config. Add native customizations through config plugins. EAS Build handles compilation in the cloud.

Bare workflow: Full access to ios/ and android/ directories. Use when you need custom native code that cannot be expressed through config plugins or Expo Modules. You still get Expo SDK modules, EAS services, and Expo Router - you just manage native projects yourself.

Decision guide:

• Start with managed. Always.
• Move to bare only when you hit a wall that config plugins cannot solve
• Common reasons to go bare: proprietary native SDKs with complex linking, custom app extensions (widgets, watch apps), or heavily modified native build configurations

Expo Prebuild

Prebuild generates native projects from your app.config.ts and config plugins.

# Generate native projects
npx expo prebuild

# Clean regenerate (wipe ios/ and android/ first)
npx expo prebuild --clean

# Generate for one platform only
npx expo prebuild --platform ios

Key principle: Treat ios/ and android/ as generated artifacts. Do not manually edit them in managed workflow - use config plugins instead. Add ios/ and android/ to .gitignore in managed projects.

Expo SDK Modules (commonly used)

Always install Expo modules with npx expo install (not npm install) to get the correct version for your SDK.

Config Plugins

Config plugins modify native project files during prebuild. They are the primary mechanism for native customization in managed workflow.

Built-in plugin API

import {
  ConfigPlugin,
  withInfoPlist,        // Modify iOS Info.plist
  withEntitlementsPlist, // Modify iOS entitlements
  withAndroidManifest,  // Modify AndroidManifest.xml
  withAppDelegate,      // Modify AppDelegate
  withMainActivity,     // Modify MainActivity
  withProjectBuildGradle, // Modify project build.gradle
  withAppBuildGradle,   // Modify app build.gradle
  withPlugins,          // Compose multiple plugins
  withDangerousMod,     // Raw file system access (last resort)
} from 'expo/config-plugins';

Plugin structure

// plugins/withMyPlugin.ts
import { ConfigPlugin, withInfoPlist } from 'expo/config-plugins';

interface PluginProps {
  apiKey: string;
}

const withMyPlugin: ConfigPlugin<PluginProps> = (config, { apiKey }) => {
  return withInfoPlist(config, (config) => {
    config.modResults.MY_API_KEY = apiKey;
    return config;
  });
};

export default withMyPlugin;

Usage in app.config.ts

export default {
  plugins: [
    ['./plugins/withMyPlugin', { apiKey: 'abc123' }],
    'expo-camera', // Expo modules are also config plugins
    ['expo-notifications', { icon: './assets/notification-icon.png' }],
  ],
};

Plugin best practices

• Always check if a community plugin exists before writing your own
• Use typed mods (withInfoPlist, withAndroidManifest) over withDangerousMod
• Test plugins by running npx expo prebuild --clean and inspecting the generated native files
• Plugins run in order - later plugins can override earlier ones

EAS Services

EAS Build

Cloud build service. No local Xcode or Android Studio needed.

eas build --platform ios --profile development  # Dev client build
eas build --platform android --profile preview  # Internal distribution
eas build --platform all --profile production    # Store builds

EAS Submit

Submit builds directly to App Store Connect and Google Play.

eas submit --platform ios --latest
eas submit --platform android --latest

EAS Update

Over-the-air JS bundle updates. See references/ota-updates.md for details.

EAS Metadata (Beta)

Manage app store metadata (screenshots, descriptions) as code.

eas metadata:pull   # Pull current metadata from stores
eas metadata:push   # Push metadata to stores

Development Builds (Dev Client)

Custom development builds that include your native modules but with the Expo Go-like development experience.

# Create a dev client build
eas build --platform ios --profile development

# Start the dev server
npx expo start --dev-client

Use dev clients instead of Expo Go when:

• Your app uses custom native modules
• You need to test config plugin changes
• You are using libraries not included in Expo Go (e.g., react-native-maps, @react-native-firebase)

Expo Image (expo-image)

High-performance replacement for React Native's <Image>. Supports:

• Automatic caching with configurable policies
• BlurHash and ThumbHash placeholders
• AVIF, WebP, animated GIF/WebP, SVG
• Content-fit modes (cover, contain, fill, scale-down)
• Recycling for list performance

import { Image } from 'expo-image';

<Image
  source={{ uri: 'https://example.com/photo.jpg' }}
  placeholder={{ blurhash: 'LGF5]+Yk^6#M@-5c,1J5@[or[Q6.' }}
  contentFit="cover"
  transition={200}
  style={{ width: 300, height: 200 }}
/>

Always prefer expo-image over React Native's built-in <Image> for production apps.

Native Modules Reference

Choosing Your Approach

Expo Modules API

The recommended way to write native modules. Provides a unified Swift/Kotlin API with automatic TypeScript type generation.

Scaffold a new module

# Local module (lives inside your project)
npx create-expo-module my-module --local

# Standalone module (publishable to npm)
npx create-expo-module my-module

Module definition (iOS - Swift)

// modules/my-module/ios/MyModule.swift
import ExpoModulesCore

public class MyModule: Module {
  public func definition() -> ModuleDefinition {
    // Module name (used in JS import)
    Name("MyModule")

    // Synchronous function
    Function("add") { (a: Int, b: Int) -> Int in
      return a + b
    }

    // Async function with Promise
    AsyncFunction("fetchUser") { (userId: String, promise: Promise) in
      DispatchQueue.global().async {
        // Network call or heavy work
        let user = UserService.fetch(id: userId)
        promise.resolve(["name": user.name, "email": user.email])
      }
    }

    // Constants exposed to JS
    Constants {
      return ["PI": Double.pi, "platform": "ios"]
    }

    // Events emitted to JS
    Events("onProgress", "onComplete")

    // Native view component
    View(MyNativeView.self) {
      Prop("color") { (view, color: UIColor) in
        view.backgroundColor = color
      }

      Events("onTap")
    }
  }
}

Module definition (Android - Kotlin)

// modules/my-module/android/src/main/java/expo/modules/mymodule/MyModule.kt
package expo.modules.mymodule

import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition

class MyModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("MyModule")

    Function("add") { a: Int, b: Int ->
      a + b
    }

    AsyncFunction("fetchUser") { userId: String ->
      val user = UserService.fetch(userId)
      mapOf("name" to user.name, "email" to user.email)
    }

    Constants(
      "PI" to Math.PI,
      "platform" to "android"
    )

    Events("onProgress", "onComplete")

    View(MyNativeView::class) {
      Prop("color") { view: MyNativeView, color: Int ->
        view.setBackgroundColor(color)
      }

      Events("onTap")
    }
  }
}

TypeScript interface

// modules/my-module/index.ts
import MyModule from './src/MyModuleModule';

export function add(a: number, b: number): number {
  return MyModule.add(a, b);
}

export async function fetchUser(userId: string): Promise<{ name: string; email: string }> {
  return MyModule.fetchUser(userId);
}

export const PI: number = MyModule.PI;

Native view component

// modules/my-module/src/MyNativeView.tsx
import { requireNativeView } from 'expo';
import { ViewProps } from 'react-native';

interface MyNativeViewProps extends ViewProps {
  color?: string;
  onTap?: () => void;
}

const NativeView = requireNativeView<MyNativeViewProps>('MyNativeView');

export function MyNativeView(props: MyNativeViewProps) {
  return <NativeView {...props} />;
}

TurboModules (New Architecture)

For React Native projects not using Expo, TurboModules provide JSI-based native module access.

Codegen spec

// NativeMyModule.ts (Codegen reads this)
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  add(a: number, b: number): number;
  fetchUser(userId: string): Promise<{ name: string; email: string }>;
}

export default TurboModuleRegistry.getEnforcing<Spec>('MyModule');

Enable New Architecture

// android/gradle.properties
newArchEnabled=true

// ios - set in Podfile or via env
// ENV['RCT_NEW_ARCH_ENABLED'] = '1'

Or in Expo:

// app.json
{
  "expo": {
    "newArchEnabled": true
  }
}

JSI (JavaScript Interface)

JSI allows C++ code to be called directly from JavaScript without serialization. Used by libraries like react-native-mmkv, react-native-reanimated, and expo-sqlite.

// C++ JSI host object (simplified)
#include <jsi/jsi.h>

class MyHostObject : public facebook::jsi::HostObject {
public:
  facebook::jsi::Value get(
    facebook::jsi::Runtime& runtime,
    const facebook::jsi::PropNameID& name
  ) override {
    auto methodName = name.utf8(runtime);
    if (methodName == "add") {
      return facebook::jsi::Function::createFromHostFunction(
        runtime, name, 2,
        [](facebook::jsi::Runtime& rt, const facebook::jsi::Value& thisVal,
           const facebook::jsi::Value* args, size_t count) {
          return facebook::jsi::Value(args[0].asNumber() + args[1].asNumber());
        }
      );
    }
    return facebook::jsi::Value::undefined();
  }
};

JSI is low-level. Prefer Expo Modules API or TurboModules unless you need sub-millisecond call overhead.

Common Native Module Patterns

Emitting events to JavaScript

// iOS (Expo Modules)
self.sendEvent("onProgress", ["percent": 0.75])

// Android (Expo Modules)
sendEvent("onProgress", mapOf("percent" to 0.75))

// JavaScript listener
import { EventEmitter } from 'expo-modules-core';
import MyModule from './MyModuleModule';

const emitter = new EventEmitter(MyModule);
const subscription = emitter.addListener('onProgress', ({ percent }) => {
  console.log(`Progress: ${percent * 100}%`);
});

// Clean up
subscription.remove();

Handling platform differences

import { Platform } from 'react-native';

export function getDeviceInfo() {
  if (Platform.OS === 'ios') {
    return MyModule.getIOSSpecificInfo();
  } else {
    return MyModule.getAndroidSpecificInfo();
  }
}

Debugging Native Modules

• iOS: Open ios/*.xcworkspace in Xcode. Add breakpoints in Swift code. Use NSLog() or print().
• Android: Open android/ in Android Studio. Add breakpoints in Kotlin. Use Log.d("MyModule", message).
• Flipper: Inspect bridge messages, network calls, and layout from a desktop app.
• Metro logs: Native errors often surface in Metro terminal as red screens with stack traces.

Migration: Bridge to New Architecture

1. Replace NativeModules.MyModule imports with TurboModule codegen specs
2. Convert RCT_EXPORT_METHOD to C++ TurboModule methods (or use Expo Modules API)
3. Enable New Architecture in gradle.properties / Podfile
4. Test all native module calls - synchronous returns work differently under JSI
5. Update third-party libraries to New Architecture compatible versions

Check https://reactnative.directory for library compatibility with the New Architecture.

Navigation Reference

Expo Router vs React Navigation

Expo Router (recommended for new projects): File-based routing built on React Navigation. The file system defines your routes. Automatic deep linking, type safety, and web support.

React Navigation (direct usage): Imperative navigation configuration. Use when you need patterns Expo Router does not yet support, or in non-Expo React Native projects.

Both share the same underlying navigation primitives - stacks, tabs, drawers. Expo Router is a convenience layer, not a replacement.

Expo Router Patterns

File structure = route structure

app/
  _layout.tsx         -> Root layout (wraps all routes)
  index.tsx           -> / (home screen)
  about.tsx           -> /about
  settings/
    _layout.tsx       -> Layout for /settings/*
    index.tsx         -> /settings
    profile.tsx       -> /settings/profile
  details/
    [id].tsx          -> /details/:id (dynamic segment)
  blog/
    [...slug].tsx     -> /blog/* (catch-all route)
  (auth)/
    _layout.tsx       -> Group layout (no URL segment added)
    login.tsx         -> /login
    register.tsx      -> /register
  +not-found.tsx      -> 404 handler

Navigation actions

import { router, Link, useRouter } from 'expo-router';

// Imperative navigation
router.push('/details/123');       // Push onto stack
router.replace('/home');           // Replace current screen
router.back();                     // Go back
router.navigate('/settings');      // Navigate (reuses existing screen if present)

// Declarative navigation
<Link href="/details/123">View Details</Link>
<Link href="/details/123" asChild>
  <Pressable><Text>View Details</Text></Pressable>
</Link>

Typed routes

// Enable typed routes in app.json
{ "experiments": { "typedRoutes": true } }

// Then get autocomplete and type checking
router.push('/details/123');  // TypeScript validates this path exists

Layout navigators

// Stack layout
import { Stack } from 'expo-router';
export default function Layout() {
  return (
    <Stack screenOptions={{ headerStyle: { backgroundColor: '#f5f5f5' } }}>
      <Stack.Screen name="index" options={{ title: 'Home' }} />
      <Stack.Screen name="details/[id]" options={{ title: 'Details' }} />
    </Stack>
  );
}

// Tab layout
import { Tabs } from 'expo-router';
export default function Layout() {
  return (
    <Tabs>
      <Tabs.Screen name="index" options={{ title: 'Feed' }} />
      <Tabs.Screen name="search" options={{ title: 'Search' }} />
    </Tabs>
  );
}

// Drawer layout
import { Drawer } from 'expo-router/drawer';
export default function Layout() {
  return (
    <Drawer>
      <Drawer.Screen name="index" options={{ drawerLabel: 'Home' }} />
    </Drawer>
  );
}

Route groups

Groups organize routes without affecting the URL structure. Use parentheses for group names.

app/
  (tabs)/
    _layout.tsx       -> Tab navigator
    home.tsx          -> /home (not /(tabs)/home)
    profile.tsx       -> /profile
  (auth)/
    _layout.tsx       -> Stack navigator for auth flow
    login.tsx         -> /login
    register.tsx      -> /register

Authentication Flow Pattern

// app/_layout.tsx
import { Stack } from 'expo-router';
import { useAuth } from '../hooks/useAuth';
import { Redirect } from 'expo-router';

export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="(auth)" options={{ headerShown: false }} />
    </Stack>
  );
}

// app/(tabs)/_layout.tsx
import { Redirect } from 'expo-router';
import { useAuth } from '../../hooks/useAuth';

export default function TabsLayout() {
  const { isAuthenticated } = useAuth();
  if (!isAuthenticated) return <Redirect href="/login" />;

  return (
    <Tabs>
      <Tabs.Screen name="home" />
      <Tabs.Screen name="profile" />
    </Tabs>
  );
}

Deep Linking

Expo Router (automatic)

Deep linking works out of the box. The file path IS the URL:

• app/details/[id].tsx handles myapp://details/123 and https://myapp.com/details/123

Configure the URL scheme in app.config.ts:

{
  scheme: 'myapp',
  ios: { associatedDomains: ['applinks:myapp.com'] },
  android: {
    intentFilters: [{
      action: 'VIEW',
      autoVerify: true,
      data: [{ scheme: 'https', host: 'myapp.com', pathPrefix: '/' }],
    }],
  },
}

React Navigation (manual)

const linking = {
  prefixes: ['myapp://', 'https://myapp.com'],
  config: {
    screens: {
      Home: '',
      Details: 'details/:id',
      Settings: {
        screens: {
          Profile: 'settings/profile',
        },
      },
    },
  },
};

<NavigationContainer linking={linking}>
  {/* navigators */}
</NavigationContainer>

Nested Navigation Patterns

Tabs containing stacks

The most common pattern: each tab has its own navigation stack.

// app/(tabs)/_layout.tsx
<Tabs>
  <Tabs.Screen name="home" />
  <Tabs.Screen name="profile" />
</Tabs>

// app/(tabs)/home/_layout.tsx
<Stack>
  <Stack.Screen name="index" />
  <Stack.Screen name="details/[id]" />
</Stack>

Modal presentation

// app/_layout.tsx
<Stack>
  <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
  <Stack.Screen
    name="modal"
    options={{ presentation: 'modal', headerShown: false }}
  />
</Stack>

// Navigate to modal from anywhere
router.push('/modal');

Navigation State Persistence

Save and restore navigation state for development or user experience:

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

// In React Navigation (manual approach)
const PERSISTENCE_KEY = 'NAVIGATION_STATE';

const [initialState, setInitialState] = useState();
const [isReady, setIsReady] = useState(false);

useEffect(() => {
  AsyncStorage.getItem(PERSISTENCE_KEY).then((saved) => {
    if (saved) setInitialState(JSON.parse(saved));
    setIsReady(true);
  });
}, []);

<NavigationContainer
  initialState={initialState}
  onStateChange={(state) => AsyncStorage.setItem(PERSISTENCE_KEY, JSON.stringify(state))}
>

Common Navigation Gotchas

• Screen names must match file names in Expo Router - a typo causes "No route" errors
• Nested navigators reset when switching tabs unless you configure unmountOnBlur: false
• params are NOT reactive - use useLocalSearchParams (re-renders on change) vs useGlobalSearchParams (stays current)
• Header flickering with nested stacks - set headerShown: false on parent when child has its own header
• Back behavior on Android - hardware back button follows stack history, not tab history. Customize with BackHandler

OTA Updates Reference

How OTA Updates Work

Over-the-air updates push new JavaScript bundles and assets to users without requiring an app store submission. The native binary stays the same - only the JS layer is replaced.

What CAN be updated OTA:

• JavaScript/TypeScript code
• Images and assets bundled via require()
• JSON configuration files

What CANNOT be updated OTA:

• Native code (Swift, Kotlin, Objective-C, Java)
• Native module additions or removals
• Changes to app.json/app.config.ts that affect native configuration
• New Expo SDK modules (they include native code)

EAS Update

Expo's official OTA update service. Integrated with EAS Build.

Setup

# Install the updates client
npx expo install expo-updates

# Configure EAS Update
eas update:configure

# This adds to app.json:
# "updates": { "url": "https://u.expo.dev/<project-id>" }
# "runtimeVersion": { "policy": "appVersion" }

Publishing updates

# Update a specific branch
eas update --branch production --message "Fix login bug"

# Update with auto-generated message from git
eas update --branch production --auto

# Update only specific platforms
eas update --branch production --platform ios

# Preview what would be updated
eas update --branch preview --message "Test new feature"

Branch and channel model

Channels (mapped to build profiles)     Branches (where updates live)
-----------------------------------     ----------------------------
production channel  ------>  production branch
preview channel     ------>  preview branch
development channel ------>  development branch

• A channel is embedded in the native build at compile time
• A branch is where updates are published
• Channels point to branches. You can remap them without rebuilding.

# Point production channel to a different branch (instant rollback)
eas channel:edit production --branch rollback-v1

# View current mappings
eas channel:list

Runtime versioning

Runtime versions ensure JS updates are only applied to compatible native binaries.

// app.config.ts - recommended setup
{
  runtimeVersion: {
    policy: 'fingerprint', // Auto-detects native code changes
  },
  updates: {
    url: 'https://u.expo.dev/your-project-id',
    fallbackToCacheTimeout: 0, // Don't block app start
    checkAutomatically: 'ON_LOAD', // Check on every app open
  },
}

Update lifecycle and behavior

import * as Updates from 'expo-updates';

// Check for updates manually
async function checkForUpdate() {
  try {
    const update = await Updates.checkForUpdateAsync();
    if (update.isAvailable) {
      await Updates.fetchUpdateAsync();
      // Restart to apply - prompt user first
      await Updates.reloadAsync();
    }
  } catch (error) {
    console.log('Update check failed:', error);
  }
}

// Listen for automatic update events
Updates.addListener((event) => {
  if (event.type === Updates.UpdateEventType.UPDATE_AVAILABLE) {
    // An update was downloaded and is ready to apply
    // Show a prompt to the user
  }
  if (event.type === Updates.UpdateEventType.NO_UPDATE_AVAILABLE) {
    // Already on the latest version
  }
  if (event.type === Updates.UpdateEventType.ERROR) {
    // Update check or download failed
    console.error(event.message);
  }
});

Update strategies

Strategy 1: Silent background update (most common)

• Check on app launch, download in background
• Apply on next app open (user sees old version until restart)
• Set fallbackToCacheTimeout: 0

Strategy 2: Forced update

• Check on app launch, block until downloaded
• Set fallbackToCacheTimeout: 30000 (30s timeout)
• Use for critical fixes only - degrades UX

Strategy 3: Prompted update

• Check on app launch, notify user when ready
• Let user choose when to restart
• Best balance of UX and update speed

Rollback

# Option 1: Remap channel to a previous branch
eas channel:edit production --branch production-rollback

# Option 2: Republish a previous commit
git checkout <previous-commit>
eas update --branch production --message "Rollback to v1.2.0"
git checkout main

# Option 3: EAS Update automatically rolls back
# If an update crashes on startup, expo-updates falls back to the embedded bundle

Debugging updates

# View published updates
eas update:list --branch production

# View update details
eas update:view <update-id>

# Check what runtime version a build expects
eas build:list --platform ios --status finished

CodePush Migration

Microsoft CodePush (App Center) reached end-of-life in March 2025. Migrate to EAS Update.

Migration steps

1. Install expo-updates: npx expo install expo-updates
2. Remove react-native-code-push from your project
3. Remove CodePush wrapper from your root component
4. Configure EAS Update in app.config.ts
5. Set up branches and channels to match your CodePush deployment targets
6. Update CI/CD to use eas update instead of appcenter codepush release-react

Key differences from CodePush

Best Practices

1. Always use fingerprint runtime versioning - it prevents the most common OTA failure (JS/native mismatch)
2. Test updates on preview branch first before publishing to production
3. Set fallbackToCacheTimeout: 0 in production - never block app start for an update
4. Monitor update adoption with eas update:list and analytics events
5. Keep updates small - only ship changed JS, not the entire bundle (EAS handles this automatically with diffs)
6. Have a rollback plan - know how to remap channels before you need to
7. Use CI/CD for updates - automate eas update in your merge-to-main pipeline

# GitHub Actions example
- name: Publish OTA update
  if: github.ref == 'refs/heads/main'
  run: eas update --branch production --auto --non-interactive
  env:
    EXPO_TOKEN: ${{ secrets.EXPO_TOKEN }}

Performance Reference

Hermes Engine

Hermes is the default JS engine for React Native (since RN 0.70). It compiles JavaScript to bytecode at build time, reducing startup time and memory usage.

Key benefits

• Bytecode precompilation: No JIT needed at runtime - faster cold starts
• Optimized garbage collector: Generational GC reduces pause times
• Lower memory footprint: ~30-50% less memory than JSC for typical apps
• Hermes bytecode (.hbc): Shipped in the app bundle instead of raw JS

Verify Hermes is enabled

const isHermes = () => !!(global as any).HermesInternal;
console.log('Hermes enabled:', isHermes());

Hermes profiling

# Capture a Hermes CPU profile
npx react-native profile-hermes

# Or via Chrome DevTools
# Open chrome://inspect, connect to Hermes, use the Performance tab

Startup Time Optimization

Measurement

// Measure TTI (Time to Interactive)
import { PerformanceObserver } from 'react-native-performance';

// Or simple timestamp approach
const appStartTime = global.__APP_START_TIME__; // Set in native code
const jsLoadTime = Date.now();

// In your root component
useEffect(() => {
  const tti = Date.now() - appStartTime;
  console.log(`TTI: ${tti}ms`);
}, []);

Optimization checklist

1. Enable Hermes (default in modern RN - verify it is not disabled)
2. Reduce JS bundle size: Code split with require() calls, remove unused dependencies
3. Defer non-critical initialization: Load heavy modules lazily after first render
4. Optimize splash screen: Use expo-splash-screen to control when splash hides
5. Preload critical data: Start fetching API data in parallel with JS initialization
6. Minimize synchronous storage reads: Move AsyncStorage.getItem calls out of the render path
7. Use RAM bundles on Android: For very large apps, enables loading modules on demand

// Lazy module loading
const HeavyChart = React.lazy(() => import('./components/HeavyChart'));

// With Suspense
<Suspense fallback={<ActivityIndicator />}>
  <HeavyChart data={chartData} />
</Suspense>

FlatList Deep Optimization

Critical props

Advanced patterns

// Use FlashList for large lists (drop-in FlatList replacement)
import { FlashList } from '@shopify/flash-list';

<FlashList
  data={data}
  renderItem={renderItem}
  estimatedItemSize={80}  // Required - provide best estimate
  keyExtractor={keyExtractor}
/>

FlashList (by Shopify) uses cell recycling - it reuses view instances instead of creating/destroying them. For lists over 100 items, FlashList typically outperforms FlatList by 5-10x.

Image optimization in lists

// Use expo-image with recyclingKey for list performance
import { Image } from 'expo-image';

const renderItem = ({ item }) => (
  <Image
    source={{ uri: item.imageUrl }}
    recyclingKey={item.id}  // Enables view recycling
    placeholder={{ blurhash: item.blurhash }}
    contentFit="cover"
    transition={100}
    style={styles.thumbnail}
  />
);

Re-render Prevention

Diagnosis

1. React DevTools Profiler: Enable "Highlight updates when components render" to visualize re-renders
2. why-did-you-render: Library that logs unnecessary re-renders with reasons

npm install @welldone-software/why-did-you-render --save-dev

// wdyr.ts (import at app entry before any other imports)
import React from 'react';
if (__DEV__) {
  const whyDidYouRender = require('@welldone-software/why-did-you-render');
  whyDidYouRender(React, { trackAllPureComponents: true });
}

Common causes and fixes

State management for performance

// BAD: React Context re-renders ALL consumers on ANY state change
const AppContext = createContext({ user: null, theme: 'light', cart: [] });

// GOOD: Zustand with selectors - components only re-render for their slice
import { create } from 'zustand';

const useStore = create((set) => ({
  user: null,
  theme: 'light',
  cart: [],
  setTheme: (theme) => set({ theme }),
}));

// This component ONLY re-renders when theme changes
function ThemeToggle() {
  const theme = useStore((state) => state.theme);
  const setTheme = useStore((state) => state.setTheme);
  // ...
}

Memory Profiling

iOS

• Xcode Instruments > Allocations: Track memory growth over time
• Xcode Memory Graph Debugger: Find retain cycles and leaks

Android

• Android Studio Profiler > Memory: Real-time heap tracking
• adb shell dumpsys meminfo <package>: Snapshot memory stats

Common memory leaks in React Native

Animation Performance

Use the UI thread

// react-native-reanimated runs animations on the UI thread
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from 'react-native-reanimated';

function AnimatedBox() {
  const offset = useSharedValue(0);

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

  return (
    <Animated.View style={[styles.box, animatedStyle]}>
      <Pressable onPress={() => { offset.value = withSpring(offset.value + 50); }}>
        <Text>Move</Text>
      </Pressable>
    </Animated.View>
  );
}

Animation rules

• Never use Animated from react-native for complex animations - use react-native-reanimated
• Avoid useNativeDriver: false - it runs animations on the JS thread
• Gesture handling: use react-native-gesture-handler for 60fps gesture-driven animations
• Avoid animating width/height - use transform: scale instead
• Use layout animations from reanimated for enter/exit transitions

Bundle Size Analysis

# React Native CLI
npx react-native bundle --platform ios --dev false --entry-file index.js --bundle-output bundle.js
npx source-map-explorer bundle.js

# Expo
npx expo export --platform ios
# Inspect the generated bundles in dist/

Size reduction strategies

• Replace moment with date-fns or native Intl
• Replace lodash with individual imports or native methods
• Use expo-image instead of multiple image libraries
• Audit native dependencies - each adds to binary size on both platforms
• Enable ProGuard on Android and bitcode on iOS for release builds