Expo SDK

Overview

Expo SDK 54+ provides a managed React Native development environment with file-based routing (Expo Router), native module access, and streamlined build tooling. This skill covers app configuration, the root layout provider pattern, and key Expo/RN libraries.

Prerequisite: npx create-expo-app or Expo SDK 54+ in package.json

Workflows

Setting up a new Expo demo:

1. • Create project: npx create-expo-app [demo-name] --template blank-typescript
2. • Install core dependencies: pnpm add expo-router expo-image expo-haptics react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet @shopify/flash-list lucide-react-native nativewind tailwindcss@3
3. • Configure NativeWind (see nativewind skill)
4. • Set up root layout with provider stack
5. • Configure app.json with scheme, name, splash
6. • Add route groups and screens
7. • Run: pnpm start (Expo dev server)

Adding a new library:

1. • Install with pnpm: pnpm add [library]
2. • Check if Expo config plugin needed in app.json
3. • Rebuild dev client if native module added: npx expo prebuild

Guidance

app.json Configuration

Key fields for demo apps:

Root Layout Provider Pattern

The root app/_layout.tsx wraps the entire app with providers. Standard order:

GestureHandlerRootView (flex: 1)
  └── SafeAreaProvider
       └── ThemeProvider / Context
            └── Stack (Expo Router)

• •GestureHandlerRootView must be outermost (required by gesture handler and bottom sheets)
• •SafeAreaProvider provides safe area insets to all descendants
• •App-level context providers go between SafeAreaProvider and Stack
• •<Stack screenOptions={{ headerShown: false }} /> for custom headers

expo-image (replaces RN Image)

Use expo-image for all image rendering — provides caching, blurhash placeholders, content-fit modes, and animated transitions.

Key props:

• •source — URI string or require() for local images
• •placeholder — blurhash string for loading state
• •contentFit — 'cover' | 'contain' | 'fill'
• •transition — fade-in duration in ms (e.g., 300)

expo-haptics

Provide tactile feedback on interactions:

• •Haptics.selectionAsync() — light tap for selections, toggles
• •Haptics.impactAsync(ImpactFeedbackStyle.Medium) — button press, card tap
• •Haptics.notificationAsync(NotificationFeedbackType.Success) — action completion

Use sparingly — haptics on every touch is annoying.

Safe Area Insets

Account for device notch, status bar, and home indicator:

• •useSafeAreaInsets() — returns { top, bottom, left, right } in points
• •Apply to screen containers: paddingTop: insets.top
• •NativeWind classes: use pt-[${insets.top}px] or wrap in SafeAreaView

@gorhom/bottom-sheet

Replaces Radix Dialog for mobile modal patterns:

• •Use for detail views, selections, filters, forms
• •Define snap points: snapPoints={['25%', '50%', '90%']}
• •Backdrop: backdropComponent with press-to-dismiss
• •BottomSheetScrollView for scrollable content inside sheets
• •Requires GestureHandlerRootView as ancestor

FlashList (replaces FlatList)

High-performance list rendering from @shopify/flash-list:

• •Drop-in FlatList replacement with mandatory estimatedItemSize prop
• •estimatedItemSize={80} — estimated height of each item in points
• •Recycling architecture for smooth 60fps scrolling
• •Use contentContainerClassName for NativeWind styling

lucide-react-native

Icon library for React Native (matches web lucide-react):

• •Import individual icons: import { Home, Settings, ChevronRight } from 'lucide-react-native'
• •Props: size, color, strokeWidth
• •Consistent icon set across mobile and web codebases

StatusBar

Configure status bar appearance per screen:

• •<StatusBar style="dark" /> for light backgrounds
• •<StatusBar style="light" /> for dark backgrounds
• •Import from expo-status-bar

Best Practices

• •Wrap root layout in GestureHandlerRootView with style={{ flex: 1 }}
• •Use expo-image for all images (caching, blurhash, performance)
• •Add haptics to primary actions only (buttons, major selections) — not every touch
• •Set estimatedItemSize on all FlashList components
• •Place providers in root _layout.tsx, not in individual screens
• •Use useSafeAreaInsets() for manual padding, SafeAreaView for simple wrapping
• •Test on real device for haptics and performance verification

Anti-Patterns

• •Using React Native Image instead of expo-image
• •Using FlatList for large datasets instead of FlashList
• •Forgetting GestureHandlerRootView (causes bottom sheet and gesture crashes)
• •Overusing haptics on every interaction
• •Hardcoding status bar height instead of using safe area insets
• •Missing estimatedItemSize on FlashList (required prop, console warning)
• •Placing SafeAreaView inside ScrollView (causes layout issues)
• •Not including expo-router plugin in app.json plugins array