How to block oversized assets in a Flutter repo

Docs/Tutorials/size_guard

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

Add the size-guard check, set a size threshold and extensions, run it on changed files only, and enforce it in CI.

What you'll learn

• Adding the size-guard check command to your monorepo toolkit
• Setting a size threshold and the extensions to scan
• Running the check on changed files only
• Enforcing it in CI

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 Guard

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

archipelago generate size_guard

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_guard --config size_guard_config.json

Step 2: Understand the Generated Structure

devtools/scripts/size_guard/
└── lib/src/
    ├── commands/        # size-guard and its check subcommand
    ├── models/size_guard_config.dart
    └── services/size_guard_service.dart

example/size_guard.yaml  # Example config. It is inert until you copy it.

The hook registers SizeGuardCommand in the toolkit. It writes no CI workflow.

Step 3: Configure

Copy the example to the workspace root:

cp example/size_guard.yaml size_guard.yaml

The file needs a top-level size_guard: map:

size_guard:
  threshold: 500KB
  extensions: [png, jpg, mp4]
  ignore_paths: [some/generated/dir]
  ignore_patterns: ["**/*.g.dart"]

Without a file, the command uses built-in defaults. You can also pass --config path/to.yaml.

Step 4: Run the Check

dart run monorepo_toolkit size-guard check
dart run monorepo_toolkit size-guard check --threshold 200KB --extension png
dart run monorepo_toolkit size-guard check --stats
dart run monorepo_toolkit size-guard check --changed-only --base main

Flags:

• --threshold accepts B, KB, MB and GB (default 500KB).
• --extension and --ignore repeat. They add to the built-in lists.
• --stats prints the total files and bytes scanned.
• --changed-only scans only files changed against the base branch.

The command exits 1 when a file is over the threshold, and 0 otherwise.

Step 5: CI Integration

- name: Check file sizes
  run: dart run monorepo_toolkit size-guard check --changed-only --base origin/${{ github.base_ref }}

A PR cannot merge a 10 MB image by mistake.

Common Customizations

Customization	Where to Change
Threshold	threshold in size_guard.yaml or --threshold
Scanned file types	extensions in size_guard.yaml
Ignored paths	ignore_paths and ignore_patterns
Fast PR checks	--changed-only

Next Steps

• Set up the Monorepo Toolkit if you have not already
• Configure CI to run size guard on every PR