React Native and Expo development guide covering components, styling, animations, navigation, state management, forms, networking, performance optimization, testing, native capabilities, and engineering (project structure, deployment, SDK upgrades, CI/CD). Use when: building React Native or Expo apps, implementing animations or native UI, managing state, fetching data, writing tests, optimizing performance, deploying to App Store/Play Store, setting up CI/CD, upgrading Expo SDK, or configuring Tailwind/NativeWind.
A practical guide for building production-ready React Native and Expo applications. Covers UI, animations, state, testing, performance, and deployment.
Consult these resources as needed:
headerLargeTitle, headerBackButtonDisplayMode), links, modals, sheets, context menusexpo-image, safe areas (contentInsetAdjustmentBehavior), native controls, blur/glass effects, storagememo, bundle analysis, TTI, memory leaks, animation perfuse*Permissions hooks), haptics, notifications, biometricscomponents/ui/, stores/, services/), path aliases, SDK upgrades, EAS build/submit, CI/CD, DOM components| Purpose | Use | Instead of |
|---|---|---|
| Lists | FlashList (@shopify/flash-list) + memo items | FlatList (no view recycling) |
| Images | expo-image | RN <Image> (no cache, no WebP) |
| Press | Pressable | TouchableOpacity (legacy) |
| Audio | expo-audio | expo-av (deprecated) |
| Video | expo-video | expo-av (deprecated) |
| Animations | Reanimated 3 | RN Animated API (limited) |
| Gestures | Gesture Handler | PanResponder (legacy) |
| Platform check | process.env.EXPO_OS | Platform.OS |
| Context | React.use() | React.useContext() (React 18) |
| Safe area scroll | contentInsetAdjustmentBehavior="automatic" | <SafeAreaView> |
| SF Symbols | expo-image with source="sf:name" | expo-symbols |
| Situation | Consider |
|---|---|
| Long lists with scroll jank | Virtualized list libraries (e.g. FlashList) |
| Want Tailwind-style classes | NativeWind v4 |
| High-frequency storage reads | Sync-based storage (e.g. MMKV) |
| New project with Expo | Expo Router over bare React Navigation |
| State Type | Solution |
|---|---|
| Local UI state | useState / useReducer |
| Shared app state | Zustand or Jotai |
| Server / async data | React Query |
| Form state | React Hook Form + Zod |
| Priority | Issue | Fix |
|---|---|---|
| CRITICAL | Long list jank | FlashList + memoized items |
| CRITICAL | Large bundle | Avoid barrel imports, enable R8 |
| HIGH | Too many re-renders | Zustand selectors, React Compiler |
| HIGH | Slow startup | Disable bundle compression, native nav |
| MEDIUM | Animation drops | Only animate transform/opacity |
# 1. Create project
npx create-expo-app@latest my-app --template blank-typescript
cd my-app
# 2. Install Expo Router + core deps
npx expo install expo-router react-native-safe-area-context react-native-screens
# 3. (Optional) Common extras
npx expo install expo-image react-native-reanimated react-native-gesture-handler
Then configure:
package.json: "main": "expo-router/entry"app.json: "scheme": "my-app"App.tsx and index.tsapp/_layout.tsx as root Stack layoutapp/(tabs)/_layout.tsx for tab navigationapp/(tabs)/ (see navigation.md)For web support, also install: npx expo install react-native-web react-dom @expo/metro-runtime
Consult references before writing: when implementing navigation, lists, networking, or project setup, read the matching reference file above for patterns and pitfalls.
Try Expo Go first (npx expo start). Custom builds (eas build) only needed when using local Expo modules, Apple targets, or third-party native modules not in Expo Go.
Conditional rendering: use {count > 0 && <Text />} not {count && <Text />} (renders "0").
Animation rule: only animate transform and opacity — GPU-composited, no layout thrash.
Imports: always import directly from source, not barrel files — avoids bundle bloat.
Lists and images: before using FlatList or RN Image, check the Component Preferences table above — FlashList and expo-image are almost always the right choice.
Route files: always use kebab-case, never co-locate components/types/utils in app/.
tsconfig.json path aliases configuredEXPO_PUBLIC_API_URL env var set per environmentGestureHandlerRootView (if using gestures)contentInsetAdjustmentBehavior="automatic" on all scroll viewsFlashList instead of FlatList for lists > 20 items--profile mode, fix frames > 16mssource-map-explorer), no barrel importsFlutter development → see flutter-dev skill.
iOS native (UIKit/SwiftUI) → see ios-application-dev skill.
Android native (Kotlin/Compose) → see android-native-dev skill.
React Native is a trademark of Meta Platforms, Inc. Expo is a trademark of 650 Industries, Inc. All other product names are trademarks of their respective owners.