Setting Up Image Asset Optimization

What you'll learn

• Generating the assets optimization command for your monorepo toolkit
• Optimizing SVG, PNG, and JPEG assets automatically
• Configuring compression levels and quality thresholds
• Integrating asset optimization into CI pipelines

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• A monorepo_toolkit already generated at devtools/

Step 1: Generate the Asset Optimizer Command

archipelago generate asset_optimizer

You will be prompted for:

• appName — MyApp (must match your monorepo app name)
• isForMonorepo — true

Or use a config file:

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

archipelago generate asset_optimizer --config optimizer_config.json

Step 2: Understand the Generated Structure

The brick adds the assets command to your monorepo toolkit:

devtools/
└── lib/src/
    └── commands/
        └── assets/
            ├── assets_command.dart          # CLI entry point
            ├── optimizers/
            │   ├── svg_optimizer.dart        # SVG minification (SVGO)
            │   ├── png_optimizer.dart        # PNG compression
            │   └── jpeg_optimizer.dart       # JPEG compression
            └── config/
                └── optimization_config.dart  # Quality and size thresholds

Step 3: Optimize Assets

Run the optimizer against your asset directories:

# Optimize all assets
dart run devtools assets optimize

# Optimize specific types
dart run devtools assets optimize --type svg
dart run devtools assets optimize --type png --quality 85

# Dry run to preview savings
dart run devtools assets optimize --dry-run

Example output:

Optimizing 12 assets...
  svg/ic_home.svg          4.2 KB → 1.8 KB  (57% smaller)
  png/bg_header.png       82.0 KB → 34.5 KB  (58% smaller)
  jpg/photo_hero.jpg     240.0 KB → 95.2 KB  (60% smaller)

Total savings: 195.7 KB (58% reduction)

Step 4: Add to CI Pipeline

Run optimization as a CI check to prevent oversized assets:

- name: Check asset sizes
  run: |
    dart run devtools assets optimize --dry-run --max-size 100KB
    if [ $? -ne 0 ]; then
      echo "Assets exceed size threshold. Run 'dart run devtools assets optimize'"
      exit 1
    fi

Key Customization Points

Customization	Where to Change
JPEG quality level	--quality flag or optimization_config.dart
Max file size threshold	--max-size flag for CI enforcement
Skip specific files	optimization_config.dart — add to exclusions
Add WebP conversion	optimizers/ — add a new WebpOptimizer class

Next Steps

• Generate type-safe asset enums after optimization
• Create an asset package to organize optimized assets