flutter-reducing-app-size
Measures and optimizes the size of Flutter application bundles for deployment. Use when minimizing download size or meeting app store package constraints.
SKILL.mdskills/flutter/reducing-app-size/SKILL.md
GitHubFlutter App Size Optimization
Contents
- Core Concepts
- Workflow: Generating Size Analysis
- Workflow: Analyzing in DevTools
- Workflow: Estimating iOS Download Size
- Workflow: Size Reduction Strategies
- Examples
Core Concepts
- Debug vs. Release: Never use debug builds to measure app size. Debug builds include VM overhead and lack AOT compilation and tree-shaking.
- Upload vs. Download Size: The upload package (APK, AAB, IPA) size ≠ end-user download size. App stores filter architectures and asset densities per device.
- AOT Tree-Shaking: Dart AOT compiler automatically removes unused/unreachable code in profile and release modes.
- Size Analysis JSON: The
--analyze-sizeflag generates a*-code-size-analysis_*.jsondetailing byte sizes of packages, libraries, classes, and functions.
Workflow: Generating Size Analysis
- Determine the target platform (apk, appbundle, ios, linux, macos, windows).
- Run the Flutter build command with
--analyze-size. - Locate the generated
*-code-size-analysis_*.jsoninbuild/.
Platform-Specific Commands
# Android App Bundle
flutter build appbundle --analyze-size --target-platform=android-arm64
# Android APK
flutter build apk --analyze-size --target-platform=android-arm64
# iOS
flutter build ios --analyze-size
# Desktop
flutter build macos --analyze-size
Note: iOS
--analyze-sizecreates a.appfile useful for relative sizing, but not for estimating final App Store download size. Use the iOS estimation workflow below.
Workflow: Analyzing in DevTools
- Launch DevTools:
dart devtools. - Select "Open app size tool" from the landing page.
- Upload the generated
*-code-size-analysis_*.json. - Inspect treemap/tree view to identify large packages, libraries, or assets.
- Feedback Loop:
- Identify largest contributors to app size.
- Determine if the dependency/asset is strictly necessary.
- Remove, replace, or optimize the identified component.
- Regenerate Size Analysis JSON and compare using DevTools "Diff" tab.
Workflow: Estimating iOS Download Size
- Configure app version and build number in
pubspec.yaml. - Generate Xcode archive:
flutter build ipa --export-method development. - Open archive (
build/ios/archive/*.xcarchive) in Xcode. - Click Distribute App → select Development.
- App Thinning: select All compatible device variants.
- Check Strip Swift symbols.
- Sign and export the IPA.
- Open exported directory and review
App Thinning Size Report.txt.
Reading the Size Report
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
The compressed size = end-user download size. The uncompressed size = on-device footprint.
Workflow: Size Reduction Strategies
Apply these strategies to reduce the compiled footprint:
- Split Debug Info: Strip debug symbols and store separately.
flutter build apk --obfuscate --split-debug-info=build/app/outputs/symbols - Remove Unused Resources: Audit
pubspec.yamlandassets/directory. Delete unreferenced images, fonts, and files. - Minimize Library Resources: Review third-party packages. If a package imports massive resources (e.g., large icon sets) but only a fraction is used, consider alternatives.
- Compress Media: Compress PNG/JPEG assets using
pngquant,imageoptim, or convert to WebP before bundling. - Use Deferred Components: For large apps, use deferred loading to download features on demand.
- Audit Dependencies: Remove unused packages from
pubspec.yaml. Each package adds to the binary.
Size Impact Reference
| Optimization | Typical Savings |
|---|---|
--split-debug-info + --obfuscate |
10-20% of binary |
| Removing unused assets | Varies (often 1-5 MB) |
| WebP conversion for images | 25-35% per image |
| Removing unused packages | Varies significantly |
Anti-patterns
- ❌ Measuring app size from debug builds
- ❌ Assuming APK/IPA size equals user download size
- ❌ Including large icon font packages (e.g., full FontAwesome) when only a few icons are used
- ❌ Bundling uncompressed high-resolution images
- ❌ Keeping unused packages in
pubspec.yaml