React Native & Expo Development Guide
A practical guide for building production-ready React Native and Expo applications. Covers UI, animations, state, testing, performance, and deployment.
References
Consult these resources as needed:
- references/navigation.md — Expo Router: Stack, Tabs, NativeTabs (
headerLargeTitle, headerBackButtonDisplayMode), links, modals, sheets, context menus
- references/components.md — FlashList patterns,
expo-image, safe areas (contentInsetAdjustmentBehavior), native controls, blur/glass effects, storage
- references/styling.md — StyleSheet, NativeWind/Tailwind, platform styles, theming, dark mode
- references/animations.md — Reanimated 3: entering/exiting, shared values, gestures, scroll-driven
- references/state-management.md — Zustand (selectors, persist), Jotai (atoms, derived), React Query, Context
- references/forms.md — React Hook Form + Zod: validation, multi-step, dynamic arrays
- references/networking.md — fetch wrapper, React Query (optimistic updates), auth tokens, offline, API routes, webhooks
- references/performance.md — Profiling workflow, FlashList +
memo, bundle analysis, TTI, memory leaks, animation perf
- references/testing.md — Jest, React Native Testing Library, E2E with Maestro
- references/native-capabilities.md — Camera, location, permissions (
use*Permissions hooks), haptics, notifications, biometrics
- references/engineering.md — Project layout (
components/ui/, stores/, services/), path aliases, SDK upgrades, EAS build/submit, CI/CD, DOM components
Quick Reference
Component Preferences
| 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 |
Scaling Up
| 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 Management
| 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 |
Performance Priorities
| 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 |
New Project Init
# 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:
- Set entry point in
package.json: "main": "expo-router/entry"
- Add scheme in
app.json: "scheme": "my-app"
- Delete
App.tsx and index.ts
- Create
app/_layout.tsx as root Stack layout
- Create
app/(tabs)/_layout.tsx for tab navigation
- Create route files in
app/(tabs)/ (see navigation.md)
For web support, also install: npx expo install react-native-web react-dom @expo/metro-runtime
Core Principles
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/.
Checklist
New Project Setup
Before Shipping
Flutter 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.
1---
2name: react-native-dev
3description: |
4 React Native and Expo development guide covering components, styling, animations, navigation,
5 state management, forms, networking, performance optimization, testing, native capabilities,
6 and engineering (project structure, deployment, SDK upgrades, CI/CD).
7 Use when: building React Native or Expo apps, implementing animations or native UI, managing
8 state, fetching data, writing tests, optimizing performance, deploying to App Store/Play Store,
9 setting up CI/CD, upgrading Expo SDK, or configuring Tailwind/NativeWind.
10description_zh: "React Native 跨平台开发指南"
11description_en: "React Native & Expo development guide"
12license: MIT
13metadata:
14 source: https://skillmd.com/skills/infometa/react-native-dev
15 version: "1.0.0"
16 category: mobile
17 sources:
18 - Expo documentation (docs.expo.dev)
19 - React Native documentation (reactnative.dev)
20 - EAS (Expo Application Services) documentation
21display_name: "react-native-dev"
22display_name_en: "react-native-dev"
23visibility: "public"
24---
25
26# React Native & Expo Development Guide
27
28A practical guide for building production-ready React Native and Expo applications. Covers UI, animations, state, testing, performance, and deployment.
29
30## References
31
32Consult these resources as needed:
33
34- [references/navigation.md](references/navigation.md) — Expo Router: Stack, Tabs, NativeTabs (`headerLargeTitle`, `headerBackButtonDisplayMode`), links, modals, sheets, context menus
35- [references/components.md](references/components.md) — FlashList patterns, `expo-image`, safe areas (`contentInsetAdjustmentBehavior`), native controls, blur/glass effects, storage
36- [references/styling.md](references/styling.md) — StyleSheet, NativeWind/Tailwind, platform styles, theming, dark mode
37- [references/animations.md](references/animations.md) — Reanimated 3: entering/exiting, shared values, gestures, scroll-driven
38- [references/state-management.md](references/state-management.md) — Zustand (selectors, persist), Jotai (atoms, derived), React Query, Context
39- [references/forms.md](references/forms.md) — React Hook Form + Zod: validation, multi-step, dynamic arrays
40- [references/networking.md](references/networking.md) — fetch wrapper, React Query (optimistic updates), auth tokens, offline, API routes, webhooks
41- [references/performance.md](references/performance.md) — Profiling workflow, FlashList + `memo`, bundle analysis, TTI, memory leaks, animation perf
42- [references/testing.md](references/testing.md) — Jest, React Native Testing Library, E2E with Maestro
43- [references/native-capabilities.md](references/native-capabilities.md) — Camera, location, permissions (`use*Permissions` hooks), haptics, notifications, biometrics
44- [references/engineering.md](references/engineering.md) — Project layout (`components/ui/`, `stores/`, `services/`), path aliases, SDK upgrades, EAS build/submit, CI/CD, DOM components
45
46## Quick Reference
47
48### Component Preferences
49
50| Purpose | Use | Instead of |
51|---------|-----|------------|
52| Lists | `FlashList` (`@shopify/flash-list`) + `memo` items | `FlatList` (no view recycling) |
53| Images | `expo-image` | RN `<Image>` (no cache, no WebP) |
54| Press | `Pressable` | `TouchableOpacity` (legacy) |
55| Audio | `expo-audio` | `expo-av` (deprecated) |
56| Video | `expo-video` | `expo-av` (deprecated) |
57| Animations | Reanimated 3 | RN Animated API (limited) |
58| Gestures | Gesture Handler | PanResponder (legacy) |
59| Platform check | `process.env.EXPO_OS` | `Platform.OS` |
60| Context | `React.use()` | `React.useContext()` (React 18) |
61| Safe area scroll | `contentInsetAdjustmentBehavior="automatic"` | `<SafeAreaView>` |
62| SF Symbols | `expo-image` with `source="sf:name"` | `expo-symbols` |
63
64### Scaling Up
65
66| Situation | Consider |
67|-----------|----------|
68| Long lists with scroll jank | Virtualized list libraries (e.g. FlashList) |
69| Want Tailwind-style classes | NativeWind v4 |
70| High-frequency storage reads | Sync-based storage (e.g. MMKV) |
71| New project with Expo | Expo Router over bare React Navigation |
72
73### State Management
74
75| State Type | Solution |
76|------------|----------|
77| Local UI state | `useState` / `useReducer` |
78| Shared app state | Zustand or Jotai |
79| Server / async data | React Query |
80| Form state | React Hook Form + Zod |
81
82### Performance Priorities
83
84| Priority | Issue | Fix |
85|----------|-------|-----|
86| CRITICAL | Long list jank | `FlashList` + memoized items |
87| CRITICAL | Large bundle | Avoid barrel imports, enable R8 |
88| HIGH | Too many re-renders | Zustand selectors, React Compiler |
89| HIGH | Slow startup | Disable bundle compression, native nav |
90| MEDIUM | Animation drops | Only animate `transform`/`opacity` |
91
92## New Project Init
93
94```bash
95# 1. Create project
96npx create-expo-app@latest my-app --template blank-typescript
97cd my-app
98
99# 2. Install Expo Router + core deps
100npx expo install expo-router react-native-safe-area-context react-native-screens
101
102# 3. (Optional) Common extras
103npx expo install expo-image react-native-reanimated react-native-gesture-handler
104```
105
106Then configure:
107
1081. Set entry point in `package.json`: `"main": "expo-router/entry"`
1092. Add scheme in `app.json`: `"scheme": "my-app"`
1103. Delete `App.tsx` and `index.ts`
1114. Create `app/_layout.tsx` as root Stack layout
1125. Create `app/(tabs)/_layout.tsx` for tab navigation
1136. Create route files in `app/(tabs)/` (see [navigation.md](references/navigation.md))
114
115For web support, also install: `npx expo install react-native-web react-dom @expo/metro-runtime`
116
117## Core Principles
118
119**Consult references before writing**: when implementing navigation, lists, networking, or project setup, read the matching reference file above for patterns and pitfalls.
120
121**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.
122
123**Conditional rendering**: use `{count > 0 && <Text />}` not `{count && <Text />}` (renders "0").
124
125**Animation rule**: only animate `transform` and `opacity` — GPU-composited, no layout thrash.
126
127**Imports**: always import directly from source, not barrel files — avoids bundle bloat.
128
129**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.
130
131**Route files**: always use kebab-case, never co-locate components/types/utils in `app/`.
132
133## Checklist
134
135### New Project Setup
136- [ ] `tsconfig.json` path aliases configured
137- [ ] `EXPO_PUBLIC_API_URL` env var set per environment
138- [ ] Root layout has `GestureHandlerRootView` (if using gestures)
139- [ ] `contentInsetAdjustmentBehavior="automatic"` on all scroll views
140- [ ] `FlashList` instead of `FlatList` for lists > 20 items
141
142### Before Shipping
143- [ ] Profile in `--profile` mode, fix frames > 16ms
144- [ ] Bundle analyzed (`source-map-explorer`), no barrel imports
145- [ ] R8 enabled for Android
146- [ ] Unit + component tests for critical paths
147- [ ] E2E flows for login, core feature, checkout
148
149---
150
151Flutter development → see `flutter-dev` skill.
152iOS native (UIKit/SwiftUI) → see `ios-application-dev` skill.
153Android native (Kotlin/Compose) → see `android-native-dev` skill.
154
155*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.*