flutter-app-size-optimization

Goal

Analyzes and optimizes Flutter application size by measuring build artifacts, generating size analysis reports, utilizing Dart DevTools for component breakdown, and implementing specific size reduction strategies such as debug info splitting, resource compression, and platform-specific tree-shaking. Assumes a configured Flutter environment and target platform availability.

Decision Logic

Use the following decision tree to determine the correct measurement and optimization path:

1. Is the user measuring Android or Desktop (Linux/macOS/Windows)?
   • Yes: Run flutter build <platform> --analyze-size. Proceed to DevTools analysis.
   • No: Proceed to step 2.
2. Is the user measuring iOS?
   • Yes: Run flutter build ipa --export-method development and generate an Xcode App Thinning Size Report for accurate download estimates.
3. Is the user analyzing the breakdown of components?
   • Yes: Launch dart devtools, open the App Size Tool, and upload the generated *-code-size-analysis_*.json file.
4. Is the user applying size reduction strategies?
   • Yes: Apply --split-debug-info, compress assets, and implement Platform checks for aggressive tree-shaking.

Instructions

1. Determine Target Platform and Baseline STOP AND ASK THE USER: "Which platform (apk, appbundle, ios, linux, macos, windows) are you targeting for size optimization, and do you have a specific size reduction goal?"

2. Generate Size Analysis File Execute the Flutter build command with the --analyze-size flag to compile Dart with code size usage recording.

   # Replace <platform> with apk, appbundle, ios, linux, macos, or windows
   flutter build <platform> --analyze-size
   

   Note: This generates a *-code-size-analysis_*.json file in the build/ directory and prints a high-level summary to the terminal.

3. Generate iOS App Size Report (iOS Only) If targeting iOS, the .app file generated by --analyze-size only evaluates relative size. For an accurate end-user download estimate, generate an Xcode App Size Report.

   flutter build ipa --export-method development
   

   • Follow up by instructing the user to:
     1. Open the archive (build/ios/archive/*.xcarchive) in Xcode.
     2. Click Distribute App -> Development.
     3. In App Thinning, select "all compatible device variants".
     4. Select Strip Swift symbols.
     5. Export the IPA and review the App Thinning Size Report.txt.

4. Analyze Components in DevTools Launch DevTools to inspect the JSON analysis file.

   dart devtools
   

   • Instruct the user to open the "App Size Tool" in the DevTools browser UI and upload the *-code-size-analysis_*.json file.
   • Use the Treemap or Dominator Tree to identify large packages, libraries, or assets.

5. Implement Size Reduction Strategies Apply the following strategies to the build process and codebase:

   Strategy A: Split Debug Info and Obfuscate Extract debug symbols from the compiled binary to reduce the final artifact size.

   flutter build appbundle --obfuscate --split-debug-info=build/app/outputs/symbols/
   

   Strategy B: Platform-Specific Tree Shaking Use dart:io Platform checks to ensure the Dart AOT compiler removes unreachable code for the target platform.

   import 'dart:io';
   
   void initializePlatformSpecificFeatures() {
     if (Platform.isWindows) {
       // Windows-specific imports and logic
       // The AOT compiler will strip this out when building for Android/iOS
       _initWindowsFeatures();
     } else if (Platform.isAndroid) {
       _initAndroidFeatures();
     }
   }
   

6. Validate and Fix After applying reduction strategies, regenerate the size analysis file.

   flutter build <platform> --analyze-size
   

   STOP AND ASK THE USER: "Please upload the new *-code-size-analysis_*.json file to DevTools and compare it with the original using the 'Diff' tab. Did the app size decrease to meet your requirements?"

   • Error State: If the size did not decrease, verify that --split-debug-info was applied correctly and that large assets (PNG/JPEG) have been compressed or removed.

Constraints

• NEVER use debug builds (flutter run or standard IDE play buttons) to measure app size. They contain debugging overhead and are not representative of production sizes.
• NEVER assume the upload package size (e.g., a universal APK or AAB) is the exact download size for end-users. App stores filter native libraries and asset densities.
• ALWAYS provide a valid directory path when using the --split-debug-info flag.
• DO NOT rely solely on the iOS .app file size; always use the Xcode App Thinning Size Report for accurate iOS download size estimates.
• ALWAYS ensure that Platform checks use dart:io constants directly so the AOT compiler can accurately perform tree-shaking.