React Native Architecture

Production patterns for React Native with Expo, covering project setup, navigation, state management, native integration, offline-first, performance, and CI/CD.

When to Use

• Starting a new React Native or Expo project

• Implementing complex navigation patterns

• Integrating native modules and platform APIs

• Building offline-first mobile applications

• Optimizing React Native performance

• Setting up CI/CD for mobile releases

Project Setup (Expo)

Create new Expo project

npx create-expo-app@latest my-app --template tabs cd my-app

Or with blank TypeScript template

npx create-expo-app@latest my-app -t expo-template-blank-typescript

Recommended Project Structure

src/ app/ # Expo Router file-based routes (tabs)/ # Tab navigator group index.tsx # Home tab profile.tsx # Profile tab _layout.tsx # Root layout +not-found.tsx # 404 screen components/ # Shared UI components ui/ # Primitives (Button, Input, Card) hooks/ # Custom hooks lib/ # Utilities, API client, storage store/ # State management (Zustand) constants/ # Theme, config, enums types/ # TypeScript definitions

Navigation

Expo Router (Recommended)

File-based routing, similar to Next.js.

// app/_layout.tsx — Root layout import { Stack } from 'expo-router';

export default function RootLayout() { return ( <Stack> <Stack.Screen name="(tabs)" options={{ headerShown: false }} /> <Stack.Screen name="modal" options={{ presentation: 'modal' }} /> </Stack> ); }

// app/(tabs)/_layout.tsx — Tab navigator import { Tabs } from 'expo-router'; import { Ionicons } from '@expo/vector-icons';

export default function TabLayout() { return ( <Tabs> <Tabs.Screen name="index" options={{ title: 'Home', tabBarIcon: ({ color }) => <Ionicons name="home" size={24} color={color} />, }} /> <Tabs.Screen name="profile" options={{ title: 'Profile' }} /> </Tabs> ); }

Navigation Patterns

Pattern Implementation

Stack <Stack> in layout — push/pop screens

Tabs <Tabs> in layout — bottom tab bar

Drawer expo-router with drawer layout

Modal presentation: 'modal' in screen options

Deep linking Automatic with Expo Router file paths

Auth flow Conditional layout based on auth state

Auth-Protected Routes

// app/_layout.tsx import { Redirect } from 'expo-router'; import { useAuth } from '@/hooks/useAuth';

export default function RootLayout() { const { isAuthenticated, isLoading } = useAuth();

if (isLoading) return <SplashScreen />; if (!isAuthenticated) return <Redirect href="/login" />;

return <Stack />; }

State Management

Scope Solution

Component useState , useReducer

Server data TanStack Query (React Query)

Global UI Zustand

Persistent MMKV + Zustand persist

Forms React Hook Form

Zustand Store

import { create } from 'zustand'; import { persist, createJSONStorage } from 'zustand/middleware'; import { zustandStorage } from '@/lib/mmkv-storage';

interface AppStore { theme: 'light' | 'dark'; setTheme: (theme: 'light' | 'dark') => void; }

export const useAppStore = create<AppStore>()( persist( (set) => ({ theme: 'light', setTheme: (theme) => set({ theme }), }), { name: 'app-store', storage: createJSONStorage(() => zustandStorage) } ) );

TanStack Query for API Data

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

function useUser(id: string) { return useQuery({ queryKey: ['user', id], queryFn: () => api.getUser(id), staleTime: 5 * 60 * 1000, }); }

function useUpdateUser() { const qc = useQueryClient(); return useMutation({ mutationFn: api.updateUser, onSuccess: (_, vars) => qc.invalidateQueries({ queryKey: ['user', vars.id] }), }); }

Native Modules & Platform APIs

Using Expo Modules

npx expo install expo-camera expo-location expo-notifications expo-file-system

import * as Location from 'expo-location';

async function getLocation() { const { status } = await Location.requestForegroundPermissionsAsync(); if (status !== 'granted') throw new Error('Permission denied'); return Location.getCurrentPositionAsync({ accuracy: Location.Accuracy.High }); }

Platform-Specific Code

import { Platform } from 'react-native';

const styles = { shadow: Platform.select({ ios: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1 }, android: { elevation: 4 }, }), };

// File-based: MyComponent.ios.tsx / MyComponent.android.tsx

Offline-First Architecture

Storage Options

Solution Use For Speed

MMKV Key-value, small data, preferences Fastest

SQLite (expo-sqlite) Structured data, queries, relations Fast

AsyncStorage Legacy key-value (avoid for new) Slow

FileSystem Large files, downloads, cache Varies

Offline Queue Pattern

import NetInfo from '@react-native-community/netinfo';

class OfflineQueue { private queue: PendingAction[] = [];

async enqueue(action: PendingAction) { this.queue.push(action); await this.persist(); this.processIfOnline(); }

private async processIfOnline() { const { isConnected } = await NetInfo.fetch(); if (!isConnected) return;

while (this.queue.length > 0) {
  const action = this.queue[0];
  try {
    await this.execute(action);
    this.queue.shift();
    await this.persist();
  } catch {
    break; // Retry later
  }
}

} }

Performance

Optimization Checklist

Area Action

Lists Use FlashList instead of FlatList

Images Use expo-image (caching, blurhash, transitions)

Animations Use react-native-reanimated (UI thread)

Heavy computation Move to worklet or background thread

Re-renders Profile with React DevTools, apply memo

Bundle Use Hermes engine (default in Expo 49+)

Startup Minimize root component, lazy load screens

FlashList (Drop-in FlatList Replacement)

import { FlashList } from '@shopify/flash-list';

<FlashList data={items} renderItem={({ item }) => <ItemCard item={item} />} estimatedItemSize={80} keyExtractor={(item) => item.id} />

Image Optimization

import { Image } from 'expo-image';

<Image source={{ uri: imageUrl }} placeholder={{ blurhash: 'LKO2?U%2Tw=w]~RBVZRi};RPxuwH' }} contentFit="cover" transition={200} style={{ width: 200, height: 200 }} />

CI/CD with EAS Build

Setup

npm install -g eas-cli eas login eas build:configure

eas.json

{ "build": { "development": { "developmentClient": true, "distribution": "internal" }, "preview": { "distribution": "internal", "ios": { "simulator": true } }, "production": {} }, "submit": { "production": { "ios": { "appleId": "you@example.com", "ascAppId": "123456789" }, "android": { "serviceAccountKeyPath": "./google-services.json" } } } }

Build Commands

eas build --platform ios --profile preview # iOS simulator build eas build --platform android --profile preview # Android APK eas build --platform all --profile production # Production builds eas submit --platform all # Submit to stores eas update --branch preview --message "Bug fix" # OTA update

Project Checklist

• Expo SDK latest (or target version)

• TypeScript configured with strict mode

• Expo Router for navigation

• Zustand + MMKV for state persistence

• TanStack Query for server state

• FlashList for performant lists

• expo-image for optimized images

• Reanimated for animations

• EAS Build configured for CI/CD

• Deep linking tested

• Offline handling implemented

• Platform-specific code isolated

• Error boundaries at route level