React Native navigation patterns

// navigation/types.ts
import { NativeStackNavigationProp } from '@react-navigation/native-stack';

export type RootStackParamList = {
  Auth: undefined;
  Home: { userId: string; theme: 'light' | 'dark' };
  Profile: { userId: string };
  Settings: undefined;
  DeepLinkTarget: { path: string; params?: Record<string, string> };
};

export type RootStackNavigationProp = NativeStackNavigationProp<RootStackParamList>;

// navigation/service.ts
import { createNavigationContainerRef, CommonActions } from '@react-navigation/native';
import { RootStackParamList } from './types';

export const navigationRef = createNavigationContainerRef<RootStackParamList>();

export function navigate<RouteName extends keyof RootStackParamList>(
  name: RouteName,
  params?: RootStackParamList[RouteName]
) {
  if (navigationRef.isReady()) {
    navigationRef.navigate(name, params);
  }
}

export function resetAndNavigate<RouteName extends keyof RootStackParamList>(
  name: RouteName,
  params?: RootStackParamList[RouteName]
) {
  if (navigationRef.isReady()) {
    navigationRef.dispatch(
      CommonActions.reset({
        index: 0,
        routes: [{ name, params }],
      })
    );
  }
}

// navigation/AppNavigator.tsx
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import {

useColorScheme } from 'react-native'; import { navigationRef } from './service'; import { RootStackParamList } from './types'; import HomeScreen from '../screens/HomeScreen'; import AuthScreen from '../screens/AuthScreen'; import ProfileScreen from '../screens/ProfileScreen'; import SettingsScreen from '../screens/SettingsScreen'; import DeepLinkScreen from '../screens/DeepLinkScreen';

const Stack = createNativeStackNavigator<RootStackParamList>();

const linking = { prefixes: ['myapp://', 'https://myapp.com'], config: { screens: { Auth: 'auth', Home: 'home/:userId?theme=:theme', Profile: 'profile/:userId', Settings: 'settings', DeepLinkTarget: 'target/:path', }, }, };

export default function AppNavigator() { const colorScheme = useColorScheme();

return ( <NavigationContainer ref={navigationRef} linking={linking} theme={colorScheme === 'dark' ? DarkTheme : DefaultTheme} > <Stack.Navigator screenOptions={{ headerShown: false, animation: 'slide_from_right', }} > <Stack.Screen name="Auth" component={AuthScreen} /> <Stack.Screen name="Home" component={HomeScreen} /> <Stack.Screen name="Profile" component={ProfileScreen} /> <Stack.Screen name="Settings" component={SettingsScreen} /> <Stack.Screen name="DeepLinkTarget" component={DeepLinkScreen} /> </Stack.Navigator> </NavigationContainer> ); }

### Step 4: State Persistence Strategy
React Navigation v7 supports `getStateFromPath` and `getPathFromState`. Persist navigation state to AsyncStorage or MMKV to restore user context after cold starts.

```typescript
// navigation/persistence.ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import { PartialState, NavigationState } from '@react-navigation/native';
import { RootStackParamList } from './types';

const NAVIGATION_STATE_KEY = 'NAVIGATION_STATE_V1';

export async function saveNavigationState(state: NavigationState | PartialState<NavigationState>) {
  try {
    await AsyncStorage.setItem(NAVIGATION_STATE_KEY, JSON.stringify(state));
  } catch (e) {
    console.warn('Failed to persist navigation state', e);
  }
}

export async function loadNavigationState(): Promise<NavigationState | PartialState<NavigationState> | undefined> {
  try {
    const state = await AsyncStorage.getItem(NAVIGATION_STATE_KEY);
    return state ? JSON.parse(state) : undefined;
  } catch (e) {
    return undefined;
  }
}

Wire persistence into NavigationContainer:

<NavigationContainer
  ref={navigationRef}
  linking={linking}
  onStateChange={(state) => saveNavigationState(state)}
  initialState={loadNavigationState()}
>

Architecture Rationale

• Native Stack over JS Stack: createNativeStackNavigator delegates transition animations and back navigation to platform native APIs, reducing JS thread load by ~40% and eliminating bridge serialization overhead during screen swaps.
• Service Layer Decoupling: Imperative navigation calls bypass React's render cycle, preventing state desynchronization in background tasks, push handlers, and API interceptors.
• Explicit Linking Config: Hardcoded URL patterns with parameter extraction prevent ambiguous route resolution and enable deterministic deep-link hydration.
• State Persistence with Hydration: Saving only the navigation tree (not screen component state) ensures fast cold starts while allowing screens to fetch fresh data on mount. This avoids stale UI state and memory bloat.

Pitfall Guide

1. Unbounded Navigator Nesting

Mistake: Nesting TabNavigator inside StackNavigator inside DrawerNavigator without architectural boundaries. Impact: Each nesting layer retains its own screen history, multiplies memory allocation, and breaks native back behavior. Android back button traverses JS history instead of native stack, causing ANRs. Best Practice: Flatten hierarchy. Use conditional rendering or dynamic route injection instead of nested navigators. Keep tab/drawer at the root level and stack as a child.

2. Synchronous Work in useFocusEffect

Mistake: Running heavy computations, synchronous storage reads, or blocking API calls inside useFocusEffect or componentDidMount. Impact: Blocks the JS thread during screen transition. Native view waits for JS to render, causing frame drops and perceived lag. Best Practice: Defer heavy work to background threads or use InteractionManager.runAfterInteractions(). Fetch data asynchronously and render placeholders. Never block the render cycle.

3. Deep Link State Desynchronization

Mistake: Parsing deep links manually without updating navigation state or ignoring query parameters. Impact: Users land on correct screen but with missing context, causing broken flows or duplicate requests. Best Practice: Use linking.config with parameter extraction. Validate hydration in useFocusEffect and dispatch explicit state updates. Never assume URL parsing equals state synchronization.

4. Memory Leaks from Retained Screens

Mistake: Leaving unmountOnBlur disabled on all screens in tab navigators. Impact: Inactive screens retain component trees, event listeners, and network subscriptions. Memory grows linearly with tab count, triggering OOM crashes on low-end Android devices. Best Practice: Enable unmountOnBlur: true for non-critical tabs. Keep auth/session state in global stores (Zustand/Redux), not screen components. Monitor with Flipper memory profiler.

5. Ignoring Platform Back Navigation Semantics

Mistake: Treating Android hardware back and iOS swipe-back identically. Impact: Android back may exit the app instead of navigating within stack. iOS swipe may conflict with custom gesture handlers. Best Practice: Use BackHandler.addEventListener for Android only. Map it to navigation.goBack() with explicit exit conditions. Respect iOS native swipe; disable custom pan gestures that conflict with createNativeStackNavigator.

6. Hardcoded Route Strings

Mistake: Using string literals for navigation calls: navigation.navigate('Profile'). Impact: Typos cause silent failures. Refactors break routing silently. No compile-time validation. Best Practice: Use TypeScript enums or const objects. Leverage RootStackParamList for type inference. Generate route constants with build scripts if scaling beyond 50 screens.

7. Persisting Screen Component State

Mistake: Serializing entire screen state (form data, scroll position, local UI flags) into navigation persistence. Impact: Bloated AsyncStorage payloads, slow hydration, stale UI on cold start, and mismatched server state. Best Practice: Persist only navigation tree structure. Let screens hydrate from global stores or API on mount. Use optimistic UI patterns for fast perceived load times.

Production Bundle

Action Checklist

• Define ParamList interface: Map every route to its exact parameter shape for compile-time safety
• Implement navigation service: Decouple imperative calls from React components to prevent state desync
• Switch to Native Stack: Replace createStackNavigator with createNativeStackNavigator to reduce JS thread load
• Configure explicit linking: Define prefixes and path patterns with parameter extraction for deterministic deep links
• Enable selective unmounting: Set unmountOnBlur: true on non-critical tabs to control memory footprint
• Add state persistence: Save navigation tree to MMKV/AsyncStorage; hydrate on cold start without serializing screen state
• Map platform back behavior: Handle Android hardware back explicitly; respect iOS native swipe gestures
• Audit useFocusEffect: Remove synchronous operations; defer heavy work to background threads or lazy loaders

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Startup MVP (<20 screens, rapid iteration)	Expo Router	File-based routing eliminates boilerplate; fastest path to production; automatic deep-link generation	Low dev cost; moderate memory overhead acceptable for early stage
Enterprise complex flows (50+ screens, deep linking, push notifications)	React Navigation v7 + Native Stack	Type safety, service layer, and native performance scale predictably; explicit state management prevents desync	Moderate setup cost; long-term maintenance cost decreases significantly
Performance-critical app (media, real-time data, low-end Android target)	React Native Navigation (Wix)	Bypasses JS thread for screen lifecycle; lowest memory footprint; native view controller optimization	High refactor cost; requires native module expertise; best reserved for performance-bound verticals

Configuration Template

// navigation/config.ts
import { DefaultTheme, DarkTheme } from '@react-navigation/native';
import { RootStackParamList } from './types';
import { navigationRef } from './service';
import { saveNavigationState, loadNavigationState } from './persistence';

export const navigationConfig = {
  ref: navigationRef,
  linking: {
    prefixes: ['myapp://', 'https://myapp.com'],
    config: {
      screens: {
        Auth: 'auth',
        Home: 'home/:userId?theme=:theme',
        Profile: 'profile/:userId',
        Settings: 'settings',
        DeepLinkTarget: 'target/:path',
      },
    },
  },
  theme: {
    light: DefaultTheme,
    dark: DarkTheme,
  },
  persistence: {
    load: loadNavigationState,
    save: saveNavigationState,
  },
};

export type NavigationConfig = typeof navigationConfig;

Quick Start Guide

1. Install dependencies: npm install @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context
2. Create navigation/types.ts with RootStackParamList and export route parameter interfaces
3. Implement navigation/service.ts with createNavigationContainerRef and navigate/resetAndNavigate helpers
4. Replace your root navigator with createNativeStackNavigator, wire linking, theme, and persistence callbacks, then mount NavigationContainer with the service ref