React Native vs Flutter 2025: The Complete Cross-Platform Mobile Development Guide

// TurboModule definition (New Architecture)
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  getConstants(): {
    platform: string;
    version: number;
  };
  multiply(a: number, b: number): Promise<number>;
}

export default TurboModuleRegistry.getEnforcing<Spec>('Calculator');

// Functional component + Hooks
import React, { useState, useCallback } from 'react';
import { View, Text, FlatList, StyleSheet, Pressable } from 'react-native';

interface User {
  id: string;
  name: string;
  email: string;
}

const UserListScreen: React.FC = () => {
  const [users, setUsers] = useState<User[]>([]);
  const [refreshing, setRefreshing] = useState(false);

  const onRefresh = useCallback(async () => {
    setRefreshing(true);
    try {
      const response = await fetch('https://api.example.com/users');
      const data = await response.json();
      setUsers(data);
    } finally {
      setRefreshing(false);
    }
  }, []);

  const renderItem = useCallback(({ item }: { item: User }) => (
    <Pressable style={styles.card}>
      <Text style={styles.name}>{item.name}</Text>
      <Text style={styles.email}>{item.email}</Text>
    </Pressable>
  ), []);

  return (
    <FlatList
      data={users}
      renderItem={renderItem}
      keyExtractor={(item) => item.id}
      refreshing={refreshing}
      onRefresh={onRefresh}
    />
  );
};

const styles = StyleSheet.create({
  card: {
    padding: 16,
    marginHorizontal: 16,
    marginVertical: 8,
    backgroundColor: '#fff',
    borderRadius: 8,
    elevation: 2,
  },
  name: { fontSize: 18, fontWeight: '600' },
  email: { fontSize: 14, color: '#666', marginTop: 4 },
});

// Pattern matching (Dart 3)
sealed class Result<T> {
  const Result();
}
class Success<T> extends Result<T> {
  final T data;
  const Success(this.data);
}
class Error<T> extends Result<T> {
  final String message;
  const Error(this.message);
}
class Loading<T> extends Result<T> {
  const Loading();
}

// Switch expression with pattern matching
Widget buildContent(Result<User> result) => switch (result) {
  Success(:final data) => UserCard(user: data),
  Error(:final message) => ErrorWidget(message: message),
  Loading() => const CircularProgressIndicator(),
};

// Records
(String name, int age) getUser() => ('Kim', 30);

// Usage
final (name, age) = getUser();
print('$name is $age years old');

// Named fields in records
({String name, int age}) getUserNamed() => (name: 'Kim', age: 30);

// StatelessWidget + state management
class UserListScreen extends StatelessWidget {
  const UserListScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Users')),
      body: Consumer<UserNotifier>(
        builder: (context, notifier, child) {
          return switch (notifier.state) {
            LoadingState() => const Center(
              child: CircularProgressIndicator(),
            ),
            ErrorState(:final message) => Center(
              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Text(message),
                  const SizedBox(height: 16),
                  ElevatedButton(
                    onPressed: notifier.retry,
                    child: const Text('Retry'),
                  ),
                ],
              ),
            ),
            SuccessState(:final data) => ListView.builder(
              itemCount: data.length,
              itemBuilder: (context, index) {
                final user = data[index];
                return UserCard(user: user);
              },
            ),
          };
        },
      ),
    );
  }
}

class UserCard extends StatelessWidget {
  final User user;
  const UserCard({super.key, required this.user});

  @override
  Widget build(BuildContext context) {
    return Card(
      margin: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
      child: ListTile(
        title: Text(user.name,
          style: Theme.of(context).textTheme.titleMedium),
        subtitle: Text(user.email),
        trailing: const Icon(Icons.chevron_right),
      ),
    );
  }
}

app/
  _layout.tsx        <- Root layout
  index.tsx          <- Home screen (/)
  (tabs)/
    _layout.tsx      <- Tab navigation
    home.tsx         <- /home
    profile.tsx      <- /profile
  users/
    [id].tsx         <- /users/123 (dynamic route)
    index.tsx        <- /users
  settings/
    _layout.tsx      <- Settings layout
    index.tsx        <- /settings

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

export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="users/[id]" options={{ title: 'User Detail' }} />
    </Stack>
  );
}

// app/users/[id].tsx
import { useLocalSearchParams } from 'expo-router';
import { View, Text } from 'react-native';

export default function UserDetail() {
  const { id } = useLocalSearchParams<{ id: string }>();

  return (
    <View>
      <Text>User ID: {id}</Text>
    </View>
  );
}

// Type-safe navigation
import { router } from 'expo-router';

function navigateToUser(userId: string) {
  router.push(`/users/${userId}`);
}

# EAS Build - cloud builds
npx eas-cli build --platform ios --profile production
npx eas-cli build --platform android --profile production

# EAS Submit - store submission
npx eas-cli submit --platform ios
npx eas-cli submit --platform android

# EAS Update - OTA updates (code only)
npx eas-cli update --branch production --message "Bug fix"

// expo-camera
import { CameraView, useCameraPermissions } from 'expo-camera';

function CameraScreen() {
  const [permission, requestPermission] = useCameraPermissions();

  if (!permission?.granted) {
    return <Button title="Grant Permission" onPress={requestPermission} />;
  }

  return <CameraView style={{ flex: 1 }} facing="back" />;
}

// expo-notifications
import * as Notifications from 'expo-notifications';

async function schedulePushNotification() {
  await Notifications.scheduleNotificationAsync({
    content: {
      title: "Reminder",
      body: 'Check your tasks!',
    },
    trigger: { seconds: 60 },
  });
}

import { create } from 'zustand';

interface UserStore {
  users: User[];
  isLoading: boolean;
  error: string | null;
  fetchUsers: () => Promise<void>;
}

const useUserStore = create<UserStore>((set) => ({
  users: [],
  isLoading: false,
  error: null,
  fetchUsers: async () => {
    set({ isLoading: true, error: null });
    try {
      const response = await fetch('https://api.example.com/users');
      const users = await response.json();
      set({ users, isLoading: false });
    } catch (error) {
      set({ error: (error as Error).message, isLoading: false });
    }
  },
}));

// Usage in component
function UserList() {
  const { users, isLoading, fetchUsers } = useUserStore();

  useEffect(() => {
    fetchUsers();
  }, [fetchUsers]);

  if (isLoading) return <ActivityIndicator />;

  return (
    <FlatList
      data={users}
      renderItem={({ item }) => <UserCard user={item} />}
    />
  );
}

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

function useUsers() {
  return useQuery({
    queryKey: ['users'],
    queryFn: () => fetch('/api/users').then(r => r.json()),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

function useCreateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (newUser: CreateUserRequest) =>
      fetch('/api/users', {
        method: 'POST',
        body: JSON.stringify(newUser),
      }).then(r => r.json()),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
}

// Provider definition
@riverpod
class UserNotifier extends _$UserNotifier {
  @override
  FutureOr<List<User>> build() async {
    return await ref.read(userRepositoryProvider).getUsers();
  }

  Future<void> addUser(CreateUserRequest request) async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(() async {
      await ref.read(userRepositoryProvider).createUser(request);
      return ref.read(userRepositoryProvider).getUsers();
    });
  }
}

// Usage in widget
class UserListScreen extends ConsumerWidget {
  const UserListScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final usersAsync = ref.watch(userNotifierProvider);

    return usersAsync.when(
      loading: () => const Center(child: CircularProgressIndicator()),
      error: (error, stack) => Center(child: Text('Error: $error')),
      data: (users) => ListView.builder(
        itemCount: users.length,
        itemBuilder: (context, index) => UserCard(user: users[index]),
      ),
    );
  }
}

// Event
sealed class UserEvent {}
class LoadUsers extends UserEvent {}
class CreateUser extends UserEvent {
  final CreateUserRequest request;
  CreateUser(this.request);
}

// State
sealed class UserState {}
class UserInitial extends UserState {}
class UserLoading extends UserState {}
class UserLoaded extends UserState {
  final List<User> users;
  UserLoaded(this.users);
}
class UserError extends UserState {
  final String message;
  UserError(this.message);
}

// Bloc
class UserBloc extends Bloc<UserEvent, UserState> {
  final UserRepository repository;

  UserBloc(this.repository) : super(UserInitial()) {
    on<LoadUsers>((event, emit) async {
      emit(UserLoading());
      try {
        final users = await repository.getUsers();
        emit(UserLoaded(users));
      } catch (e) {
        emit(UserError(e.toString()));
      }
    });
  }
}

// Type-safe routing
// app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
import { Ionicons } from '@expo/vector-icons';

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

// Deep linking automatically supported
// myapp://users/123 -> app/users/[id].tsx

final router = GoRouter(
  routes: [
    ShellRoute(
      builder: (context, state, child) => ScaffoldWithNavBar(child: child),
      routes: [
        GoRoute(
          path: '/',
          builder: (context, state) => const HomeScreen(),
        ),
        GoRoute(
          path: '/users',
          builder: (context, state) => const UserListScreen(),
          routes: [
            GoRoute(
              path: ':id',
              builder: (context, state) {
                final id = state.pathParameters['id']!;
                return UserDetailScreen(userId: id);
              },
            ),
          ],
        ),
        GoRoute(
          path: '/profile',
          builder: (context, state) => const ProfileScreen(),
        ),
      ],
    ),
  ],
);

// Usage
context.go('/users/123');
context.push('/users/123');
context.pop();

// e2e/users.test.ts
describe('User Flow', () => {
  beforeAll(async () => {
    await device.launchApp();
  });

  it('should show user list', async () => {
    await expect(element(by.id('user-list'))).toBeVisible();
  });

  it('should navigate to user detail', async () => {
    await element(by.id('user-card-1')).tap();
    await expect(element(by.text('User Detail'))).toBeVisible();
  });

  it('should pull to refresh', async () => {
    await element(by.id('user-list')).swipe('down');
    await waitFor(element(by.id('loading-indicator')))
      .not.toBeVisible()
      .withTimeout(5000);
  });
});

# .maestro/user-flow.yaml
appId: com.example.myapp
---
- launchApp
- assertVisible: "Users"
- tapOn: "Kim"
- assertVisible: "User Detail"
- back
- assertVisible: "Users"

void main() {
  testWidgets('UserCard displays user info', (tester) async {
    final user = User(id: '1', name: 'Kim', email: 'kim@test.com');

    await tester.pumpWidget(
      MaterialApp(home: UserCard(user: user)),
    );

    expect(find.text('Kim'), findsOneWidget);
    expect(find.text('kim@test.com'), findsOneWidget);
  });

  testWidgets('UserListScreen shows loading indicator', (tester) async {
    await tester.pumpWidget(
      const MaterialApp(home: UserListScreen()),
    );

    expect(find.byType(CircularProgressIndicator), findsOneWidget);
  });
}

// integration_test/app_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  testWidgets('full user flow test', (tester) async {
    await tester.pumpWidget(const MyApp());
    await tester.pumpAndSettle();

    // Verify user list
    expect(find.text('Users'), findsOneWidget);

    // Tap user card
    await tester.tap(find.text('Kim'));
    await tester.pumpAndSettle();

    // Verify detail screen
    expect(find.text('User Detail'), findsOneWidget);
  });
}

void main() {
  patrolTest('User flow with native interactions', ($) async {
    await $.pumpWidgetAndSettle(const MyApp());

    // Handle permission dialog
    await $.native.grantPermissionWhenInUse();

    // Test both Flutter widgets and native UI
    await $(#userList).scrollTo(find.text('Kim'));
    await $(find.text('Kim')).tap();
  });
}