# react-native-best-practices

> React Native and Expo best practices guide.
Use this skill when:
- Writing or reviewing React Native / Expo code
- Debugging runtime errors (undefined is not an object, maximum update depth, etc.)
- Fixing build failures (Gradle, CocoaPods, Metro bundler)
- Working with React Navigation
- Optimizing FlatList or fixing performance issues
- Handling state management (Redux, Zustand, Context)
- Working with native modules, permissions, camera, push notifications
- Fixing Expo-specific issues (EAS Build, OTA updates, config plugins)
- CSS properties not working (grid, animations, vh/vw units, pseudo-elements)
- Styling differences between iOS and Android
- Reviewing code for anti-patterns
Triggers: react native error, expo error, build failed, flatlist slow, navigation error, state not updating, memory leak, permission denied, expo build, eas build, css not working, style not applied, grid layout, animation, shadow not showing

- Author: jyggiz
- Repository: jyggiz/react-native-starter
- Version: 20260105030223
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/jyggiz/react-native-starter
- Web: https://mule.run/skillshub/@@jyggiz/react-native-starter~react-native-best-practices:20260105030223

---

---
name: react-native-best-practices
description: |
  React Native and Expo best practices guide.
  Use this skill when:
  - Writing or reviewing React Native / Expo code
  - Debugging runtime errors (undefined is not an object, maximum update depth, etc.)
  - Fixing build failures (Gradle, CocoaPods, Metro bundler)
  - Working with React Navigation
  - Optimizing FlatList or fixing performance issues
  - Handling state management (Redux, Zustand, Context)
  - Working with native modules, permissions, camera, push notifications
  - Fixing Expo-specific issues (EAS Build, OTA updates, config plugins)
  - CSS properties not working (grid, animations, vh/vw units, pseudo-elements)
  - Styling differences between iOS and Android
  - Reviewing code for anti-patterns
  Triggers: react native error, expo error, build failed, flatlist slow, navigation error, state not updating, memory leak, permission denied, expo build, eas build, css not working, style not applied, grid layout, animation, shadow not showing
---

# React Native & Expo Best Practices

## Critical Rules (Always Apply)

### Package Management
- **ALWAYS** use `npx expo install <package>` — never npm/yarn install directly
- Run `npx expo-doctor` before commits to catch version mismatches

### Code Patterns
```javascript
// ✅ Safe data access
const name = user?.profile?.name ?? 'Default';

// ✅ Correct event handler
<Button onPress={handlePress} />        // Reference
<Button onPress={() => handlePress(id)} /> // With args

// ❌ NEVER — causes infinite loop
<Button onPress={handlePress()} />      // Immediate call
```

### useEffect Rules
```javascript
// ✅ Always cleanup subscriptions
useEffect(() => {
  const controller = new AbortController();
  fetch(url, { signal: controller.signal }).then(/*...*/);
  return () => controller.abort(); // REQUIRED
}, [url]);
```

### FlatList Essentials
```javascript
// ✅ Always memoize items + use keyExtractor
const Item = memo(({ item }) => <Text>{item.title}</Text>);
const keyExtractor = useCallback((item) => item.id, []);
```

### Platform Differences
| Feature | iOS | Android |
|---------|-----|---------|
| Shadows | shadowColor/Offset/Opacity/Radius | elevation |
| fontWeight | '100'-'900' | 'normal' or 'bold' only |
| flex: 1 | Works | Requires parent height |

## Quick Fixes

| Error | Solution |
|-------|----------|
| Unable to resolve module | `rm -rf node_modules .expo && npm i && npx expo start --clear` |
| Maximum update depth | Check `onClick={fn()}` → should be `onClick={fn}` |
| Text strings must be rendered | Wrap text in `<Text>` component |
| Cannot update component while rendering | Move setState to useEffect |
| Couldn't find navigation object | Use navigationRef or ensure component is inside Navigator |

## Reference Documentation

Load these files based on the specific issue:

| Issue Type | Reference File | When to Load |
|------------|----------------|--------------|
| Runtime crashes, undefined errors | `references/runtime-errors.md` | TypeError, null/undefined access |
| Build failures | `references/build-errors.md` | Gradle, CocoaPods, Metro errors |
| Expo problems | `references/expo-issues.md` | EAS Build, Expo Go, OTA updates |
| Navigation issues | `references/navigation-errors.md` | React Navigation errors |
| Slow performance | `references/performance.md` | FlatList, memory leaks, animations |
| Styling problems | `references/styling-platform.md` | Cross-platform differences |
| CSS not working | `references/css-unsupported.md` | CSS Grid, animations, units, pseudo-elements |
| State not updating | `references/state-management.md` | Redux, Context, Zustand |
| API/fetch issues | `references/api-async.md` | Race conditions, error handling |
| Permissions, camera | `references/native-modules.md` | Native features |
| Code structure | `references/architecture.md` | Anti-patterns, project structure |

## Pre-Commit Checklist

Before any commit involving React Native code:
- [ ] No TypeScript errors
- [ ] All useEffects have cleanup functions
- [ ] FlatList items are memoized
- [ ] No inline styles in lists
- [ ] `npx expo-doctor` passes