Flutter 3 Migration: Real Pitfalls Moving from 2.x to 3.x

# Check version
flutter --version
# Flutter 2.10.5 • channel stable • Dart 2.16.8

# Check pubspec.yaml
name: my_app
environment:
  sdk: '>=2.16.0 <3.0.0'  # this needs changing

git checkout -b migration/flutter-3-upgrade

# pubspec.yaml
environment:
  sdk: '>=2.18.0 <4.0.0'  # change to this

# First upgrade Flutter SDK
flutter upgrade

# Update dependencies
flutter pub upgrade

// Flutter 2.x: Material 2 default
// Flutter 3: Material 3 default

// If you want to keep Material 2, must specify explicitly
MaterialApp(
  theme: ThemeData(
    useMaterial3: false,  // add this
  )
)

// Flutter 2.x: null safety already present, but some packages haven't updated
// Flutter 3: all dependencies must support null safety

// Check
flutter pub outdated --null-safety

# ios/Podfile
platform :ios, '12.0'  # minimum version bumped to 12.0

// Flutter 2.x
ChangeNotifierProvider(
  create: (_) => MyNotifier(),
  child: ...
)

// Flutter 3
// syntax changed
ChangeNotifierProvider(
  create: (context) => MyNotifier(),  // context parameter required
  child: ...
)

// Change all to
ChangeNotifierProvider(
  create: (context) => MyNotifier(),
  child: MyWidget(),
)

// And move Consumer inside child

// Flutter 2.x (go_router 5.x)
GoRoute(
  path: '/home',
  builder: (context, state) => HomePage(),
)

// Flutter 3 (go_router 6.x)
GoRoute(
  path: '/home',
  builder: (context, state) => HomePage(),
  // syntax unchanged, but parameter types changed
)

// Flutter 2.x
NetworkImage(url)

// Flutter 3
// NetworkImage unchanged, but cache behavior changed
// If using cached_network_image, need to update version
cached_network_image: ^3.3.0

# 1. Build check
flutter build apk --debug
flutter build ios --simulator --no-codesign

# 2. Null safety check
dart analyze --fatal-infos

# 3. Test check
flutter test

# 4. iOS CocoaPods check
cd ios && pod install && pod update