How to track Flutter app size changes against a baseline

Docs/Tutorials/size_analyzer

Pro Reference for size_analyzer: every variable, option and package it generates. Command: archipelago generate size_analyzer

Add the size-analyzer command, build with --analyze-size, read the ranked report, compare with a baseline, and update it on purpose.

What you'll learn

• Adding the size-analyzer command to your monorepo toolkit
• Building with --analyze-size and reading the ranked report
• Comparing a build with a committed baseline
• Updating the baseline when a size increase is on purpose

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Monorepo Toolkit already generated (see Monorepo Toolkit Setup)
• A Pro or Enterprise subscription

Step 1: Generate the Size Analyzer

New Pro projects already include this brick. Run it on an older project:

archipelago generate size_analyzer

The prompts are:

• appName: your app name, for example MyApp
• isForMonorepo: leave this as true

Or use a config file:

{
  "appName": "MyApp",
  "isForMonorepo": true
}

archipelago generate size_analyzer --config size_analyzer_config.json

Step 2: Understand the Generated Structure

devtools/scripts/size_analyzer/
└── lib/src/
    ├── commands/        # analyze and update-baseline
    ├── models/
    ├── reporters/
    └── services/

The hook adds the package to the workspace and the toolkit. It registers SizeAnalyzerCommand. It does not create size_baseline/ or any baseline file. The first update-baseline run writes the file at the path you pass.

Step 3: Build with Size Analysis

Flutter writes a JSON report when you pass --analyze-size:

flutter build apk --analyze-size --target-platform android-arm64

Flutter prints the path of the report, such as code-size-analysis_arm64.json, under build/. Pass that path to the analyzer. The command does not find it by itself.

Step 4: Run the Analyzer

Rank the biggest contributors:

dart run monorepo_toolkit size-analyzer analyze --json <path-to-report>

Diff against a committed baseline:

dart run monorepo_toolkit size-analyzer analyze \
  --json <path-to-report> \
  --baseline size_baseline/android.json \
  --platform android \
  --top 20

--json is required. --top defaults to 20.

Step 5: Write or Update the Baseline

Run this on merge to your main branch, or when a size increase is on purpose:

dart run monorepo_toolkit size-analyzer update-baseline \
  --json <path-to-report> \
  --output size_baseline/android.json

Both flags are required. Commit the baseline file with the code change, so reviewers see the size change in the PR.

Step 6: CI Integration

- name: Build with size analysis
  run: |
    flutter build apk --analyze-size --target-platform android-arm64

- name: Check size against baseline
  run: |
    dart run monorepo_toolkit size-analyzer analyze \
      --json <path-to-report> \
      --baseline size_baseline/android.json \
      --platform android

Find the report path in the build output and put it in the step. The step fails when the app grows past the threshold against the baseline.

Common Customizations

Customization	Where to Change
Number of ranked packages	The --top flag
Track another platform	Write a second baseline with --output size_baseline/ios.json
Report format	lib/src/reporters/size_metrics_reporter.dart

Next Steps

• Add the Detect New Library tool to catch unapproved dependencies before they land
• Configure Monitoring to correlate binary size with crash rates in production