wishtohear/bucket-water-oms/flutter-reducing-app-size

Reducing Flutter App Size

Contents

• Core Concepts
• Workflow: Generating Size Analysis Files
• Workflow: Analyzing Size Data in DevTools
• Workflow: Estimating iOS Download Size
• Workflow: Implementing Size Reduction Strategies
• Examples

Core Concepts

• Debug vs. Release: Never use debug builds to measure app size. Debug builds include VM overhead and lack Ahead-Of-Time (AOT) compilation and tree-shaking.
• Upload vs. Download Size: The size of an upload package (APK, AAB, IPA) does not represent the end-user download size. App stores filter redundant native library architectures and asset densities based on the target device.
• AOT Tree-Shaking: The Dart AOT compiler automatically removes unused or unreachable code in profile and release modes.
• Size Analysis JSON: The --analyze-size flag generates a *-code-size-analysis_*.json file detailing the byte size of packages, libraries, classes, and functions.

Workflow: Generating Size Analysis Files

Use this workflow to generate the raw data required for size analysis.

Task Progress:

• [ ] Determine the target platform (apk, appbundle, ios, linux, macos, windows).
• [ ] Run the Flutter build command with the --analyze-size flag.
• [ ] Locate the generated *-code-size-analysis_*.json file in the build/ directory.

Conditional Logic:

• If targeting Android: Run flutter build apk --analyze-size or flutter build appbundle --analyze-size.
• If targeting iOS: Run flutter build ios --analyze-size. Note: This creates a `.app` file useful for relative content sizing, but not for estimating final App Store download size. Use the [Estimating iOS Download Size](#workflow-estimating-ios-download-size) workflow for accurate iOS metrics.
• If targeting Desktop: Run flutter build [windows|macos|linux] --analyze-size.

Workflow: Analyzing Size Data in DevTools

Use this workflow to visualize and drill down into the Size Analysis JSON.

Task Progress:

• [ ] Launch DevTools by running dart devtools in the terminal.
• [ ] Select "Open app size tool" from the DevTools landing page.
• [ ] Upload the generated *-code-size-analysis_*.json file.
• [ ] Inspect the treemap or tree view to identify large packages, libraries, or assets.
• [ ] Feedback Loop:

1. Identify the largest contributors to app size.
2. Determine if the dependency or asset is strictly necessary.
3. Remove, replace, or optimize the identified component.
4. Regenerate the Size Analysis JSON and compare the new build against the old build using the DevTools "Diff" tab.

Workflow: Estimating iOS Download Size

Use this workflow to get an accurate projection of iOS download and installation sizes across different devices.

Task Progress:

• [ ] Configure the app version and build number in pubspec.yaml.
• [ ] Generate an Xcode archive by running flutter build ipa --export-method development.
• [ ] Open the generated archive (build/ios/archive/*.xcarchive) in Xcode.
• [ ] Click Distribute App and select Development.
• [ ] In the App Thinning configuration, select All compatible device variants.
• [ ] Check the option to Strip Swift symbols.
• [ ] Sign and export the IPA.
• [ ] Open the exported directory and review the App Thinning Size Report.txt file to evaluate projected sizes per device.

Workflow: Implementing Size Reduction Strategies

Apply these strategies to actively reduce the compiled footprint of the application.

Task Progress:

• [ ] Split Debug Info: Strip debug symbols from the compiled binary and store them in separate files.
• [ ] Remove Unused Resources: Audit the pubspec.yaml and assets/ directory. Delete any images, fonts, or files not actively referenced in the codebase.
• [ ] Minimize Library Resources: Review third-party packages. If a package imports massive resource files (e.g., large icon sets or localization files) but only a fraction is used, consider alternative packages or custom implementations.
• [ ] Compress Media: Compress all PNG and JPEG assets using tools like pngquant, imageoptim, or WebP conversion before bundling them into the app.

Examples

Generating Size Analysis (Android)

# Generate the size analysis JSON for an Android App Bundle
flutter build appbundle --analyze-size --target-platform=android-arm64

Splitting Debug Info (Release Build)

# Build an APK while stripping debug info to reduce binary size
flutter build apk --obfuscate --split-debug-info=build/app/outputs/symbols

Reading the iOS App Thinning Size Report

When reviewing App Thinning Size Report.txt, look for the specific target device to understand the true impact on the user:

Variant: Runner-7433FC8E-1DF4-4299-A7E8-E00768671BEB.ipa
Supported variant descriptors: [device: iPhone12,1, os-version: 13.0]
App + On Demand Resources size: 5.4 MB compressed, 13.7 MB uncompressed
App size: 5.4 MB compressed, 13.7 MB uncompressed

Interpretation: The end-user download size (compressed) is 5.4 MB, and the on-device footprint (uncompressed) is 13.7 MB.