flutter-app-size-optimization

Goal

Decision Logic

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.
   bash

   # 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.
   bash

   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.
   bash

   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.
   bash

   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.
   dart

   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.
   bash

   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.