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	INLINECODE9 (@shopify/flash-list) + memo items	INLINECODE12 (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	INLINECODE30 / INLINECODE31
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	INLINECODE32 + 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

CODEBLOCK0

Then configure:

1. 1. Set entry point in package.json: INLINECODE36
2. Add scheme in app.json: INLINECODE38
3. Delete App.tsx and INLINECODE40
4. Create app/_layout.tsx as root Stack layout
5. Create app/(tabs)/_layout.tsx for tab navigation
6. Create route files in app/(tabs)/ (see navigation.md)

For web support, also install: INLINECODE44

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

• - [ ] tsconfig.json path aliases configured
• [ ] EXPO_PUBLIC_API_URL env var set per environment
• [ ] Root layout has GestureHandlerRootView (if using gestures)
• [ ] contentInsetAdjustmentBehavior="automatic" on all scroll views
• [ ] FlashList instead of FlatList for lists > 20 items

Before Shipping

• - [ ] Profile in --profile mode, fix frames > 16ms
• [ ] Bundle analyzed (source-map-explorer), no barrel imports
• [ ] R8 enabled for Android
• [ ] Unit + component tests for critical paths
• [ ] E2E flows for login, core feature, checkout

---

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.