---
name: "flutter-app-size"
description: "Measure and reduce the size of the Flutter app bundle, APK, or IPA"
metadata:
  model: "models/gemini-3.1-pro-preview"
  last_modified: "Wed, 04 Mar 2026 22:08:14 GMT"

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