React Native Guidelines

# React Native Guidelines

Part of [Agent Skills™](https://github.com/itallstartedwithaidea/agent-skills) by [googleadsagent.ai™](https://googleadsagent.ai)

## Description

React Native Guidelines codifies 16 rules across 7 sections—Performance, Layout, Animation, Images, State, Architecture, and Platform—that prevent the most common pitfalls in cross-platform mobile development. Each rule addresses a specific failure mode unique to React Native's bridge architecture and native rendering pipeline.

React Native's performance characteristics differ fundamentally from web React. The JavaScript thread, the UI thread, and the native modules thread communicate asynchronously, and bottlenecks in any thread degrade the user experience. These guidelines focus on keeping the JS thread unblocked, using the native driver for animations, optimizing FlatList rendering, and minimizing bridge crossings.

The rules are calibrated for production applications running on both iOS and Android. Platform-specific behaviors, gesture handling differences, and navigation patterns are addressed explicitly rather than treated as edge cases.

## Use When

- Building new React Native screens or components
- Debugging performance issues on iOS or Android
- Reviewing React Native code for cross-platform correctness
- Implementing animations or gesture interactions
- Optimizing list rendering for large datasets
- Handling platform-specific behavior differences

## How It Works

```mermaid
graph TD
    A[React Native Code] --> B{Section Analysis}
    B --> C[Performance: JS Thread Budget]
    B --> D[Layout: Flexbox + Safe Areas]
    B --> E[Animation: Native Driver]
    B --> F[Images: Caching + Sizing]
    B --> G[State: Minimal Re-renders]
    B --> H[Architecture: Navigation + Deep Links]
    B --> I[Platform: iOS/Android Specifics]
    C --> J[Optimized Output]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
```

Each section contains 2-3 focused rules targeting the highest-impact issues in that category. Rules are applied during code generation and flagged during review.

## Implementation

### Performance: Optimize FlatList

```tsx
// BAD: Re-creates renderItem on every render
<FlatList
  data={items}
  renderItem={({ item }) => <Card item={item} />}
/>

// GOOD: Stable renderItem + keyExtractor + windowing config
const renderItem = useCallback(
  ({ item }: { item: Item }) => <Card item={item} />,
  []
);

<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={item => item.id}
  getItemLayout={(_, index) => ({
    length: CARD_HEIGHT,
    offset: CARD_HEIGHT * index,
    index,
  })}
  maxToRenderPerBatch={10}
  windowSize={5}
  removeClippedSubviews
/>
```

### Animation: Use Native Driver

```tsx
// BAD: JS-driven animation blocks the thread
Animated.timing(opacity, {
  toValue: 1,
  duration: 300,
  useNativeDriver: false,
}).start();

// GOOD: Native driver runs on UI thread
Animated.timing(opacity, {
  toValue: 1,
  duration: 300,
  useNativeDriver: true,
}).start();

// BEST: Reanimated for gesture-driven animations
const animatedStyle = useAnimatedStyle(() => ({
  transform: [{ translateX: withSpring(offset.value) }],
}));
```

### Platform: Safe Area Handling

```tsx
import { useSafeAreaInsets } from "react-native-safe-area-context";

function Screen({ children }: PropsWithChildren) {
  const insets = useSafeAreaInsets();
  return (
    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
      {children}
    </View>
  );
}
```

## Best Practices

- Profile with Flipper or React DevTools before optimizing—measure, do not guess
- Keep the JS thread under 16ms per frame for 60fps rendering
- Use `useNativeDriver: true` for all o