react-native

---
name: react-native
description: Use when building cross-platform mobile apps with React Native or Expo. Covers navigation, platform differences, list performance, native modules, offline behavior, and release builds. Trigger on "flatlist is laggy", "expo or bare react native", "bridge to a native module", "set up ota updates". Do not use for web React component design — see the react skill; for store signing and staged rollout, see the mobile-release skill.
metadata:
  category: mobile
  version: 1.0.0
  tags: [react-native, expo, mobile, navigation, performance]
---

# React Native

## Purpose

Build React Native applications that feel native: lists that scroll at 60fps, navigation that matches platform conventions, and a release pipeline that does not surprise you at submission.

## When to Use

- Building or reviewing a React Native or Expo application.
- Diagnosing list performance or dropped frames.
- Bridging to a native module.
- Setting up over-the-air updates and release builds.

## Capabilities

- Navigation with React Navigation or Expo Router, including deep links.
- Platform-specific behavior and styling.
- List performance: `FlashList`, virtualization, memoized rows.
- Native modules and the new architecture (Fabric, TurboModules).
- Offline support, secure storage, and background tasks.
- Release: EAS Build, OTA updates, store submission.

## Inputs

- The feature set, target platforms, and minimum OS versions.
- Whether native modules are needed (this determines Expo Go versus a dev build).
- Performance requirements, especially for lists and animation.

## Outputs

- A navigation structure with deep-link support.
- Lists that maintain frame rate with realistic data volumes.
- A build and release pipeline for both platforms.

## Workflow

1. **Choose the runtime honestly** — Expo with a development build gives you native modules and the Expo tooling. Expo Go is for prototypes; bare React Native is for teams that need full native control and are prepared to maintain it.
2. **Structure navigation first** — Stacks inside tabs, with a typed route map. Retrofitting deep links into an untyped navigator is painful.
3. **Fix lists before they are slow** — `FlashList` with a stable `keyExtractor`, memoized row components, and a fixed item size where possible. `ScrollView` with a hundred children will drop frames on a mid-range Android.
4. **Handle platform differences explicitly** — `Platform.select` for behavior, not just style. Back-button behavior, safe areas, and permission flows differ genuinely.
5. **Move animation off the JS thread** — Reanimated worklets run on the UI thread. Animating via `setState` will jank the moment the JS thread does anything else.
6. **Test the release build** — Debug builds hide performance problems entirely. Profile in release, on a real mid-range device.

## Best Practices

- The JS thread and the UI thread are separate. Any heavy JavaScript blocks interaction, and it will not show up in a simulator on a fast laptop.
- An inline arrow function as a `renderItem` re-creates every row on every render. Memoize the row component and hoist the callback.
- `useNativeDriver: true` on every `Animated` usage, or use Reanimated. Without it, every frame crosses the bridge.
- Store tokens in `expo-secure-store` or Keychain — never `AsyncStorage`, which is unencrypted plain text.
- Images are the main cause of memory pressure. Size them to the display size; do not load a 4000px original into a 100px thumbnail.
- OTA updates cannot change native code. If you added a native module, the update requires a store release.

## Examples

**A list that stays at 60fps:**

```tsx
const OrderRow = memo(function OrderRow({ order, onPress }: OrderRowProps) {
  return (
    <Pressable onPress={() => onPress(order.id)} style={styles.row}>
      <Text style={styles.title}>{order.reference}</Text>
      <Text style={styles.meta}>{order.customerName}</Text>
    </Pressable>
  );
});

export function OrderList({ orders }: { orders: Order[] }) {
  const router = useRouter();
  const onPress = useCallback((id: string) => router.push(`/orders/${id}`), [router]);

  return (
    <FlashList
      data={orders}
      renderItem={({ item }) => <OrderRow order={item} onPress={onPress} />}
      keyExtractor={(item) => item.id}
      estimatedItemSize={72}          // FlashList needs this to recycle correctly
      removeClippedSubviews
    />
  );
}
```

`onPress` is hoisted and stable, `OrderRow` is memoized, so scrolling re-renders nothing that has not changed.

**Animation on the UI thread:**

```tsx
const offset = useSharedValue(0);
const style = useAnimatedStyle(() => ({
  transform: [{ translateY: withSpring(offset.value) }],
}));

// Runs on the UI thread — unaffected by whatever the JS thread is doing.
```

## Notes

- The new architecture (Fabric + TurboModules) removes the asynchronous bridge and is the default from React Native 0.76. Older third-party native modules may not be compatible — check before upgrading.
- `estimatedItemSize` on `FlashList` is not optional in practice; a bad estimate causes visible blank space during fast scrolls.
- Hermes is the default engine and materially improves startup time and memory. If a project is still on JSC, that is usually an oversight.