How to optimize image assets in a Flutter project

Docs/Tutorials/asset_optimizer

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

Add the assets optimize command, install the tools it needs, configure each image format, and run it in CI.

What you'll learn

• Adding the assets optimize command to your monorepo toolkit
• Installing the tools it needs
• Configuring each format
• Running it in CI

Prerequisites

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

Step 1: Generate the Asset Optimizer Command

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

archipelago generate asset_optimizer

The prompts are:

• appName: the name of your app
• isForMonorepo: leave this as true

Or use a config file:

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

archipelago generate asset_optimizer --config optimizer_config.json

Step 2: Install the Tools

The command calls external tools. It checks for each enabled format first. It stops and prints install steps if one is missing.

npm install -g svgo
brew install oxipng        # or: cargo install oxipng
brew install jpegoptim     # or: apt-get install jpegoptim

Step 3: Understand the Generated Structure

devtools/
└── scripts/
    └── asset_optimizer/
        ├── example/asset_optimizer.yaml
        └── lib/src/
            ├── commands/            # assets and assets optimize
            ├── models/
            └── services/optimizers/ # svgo, oxipng, jpegoptim

The hook also writes asset_optimizer.yaml at the project root. It leaves an existing file alone.

Step 4: Configure

asset_optimizer:
  paths:
    - apps/*/assets
  svg:
    enabled: true
  png:
    enabled: true
    level: 4          # oxipng level 1 to 6, higher is smaller and slower
  jpeg:
    enabled: true
    quality: 80       # 1 to 100
  ignore:
    - '**/vendor/**'

When paths is not set, the command scans apps/*/assets, apps/*/*/assets and packages/*/assets.

Step 5: Optimize Assets

dart run monorepo_toolkit assets optimize
dart run monorepo_toolkit assets optimize --dry-run
dart run monorepo_toolkit assets optimize --config custom_optimizer.yaml

Use --dry-run to preview the savings. The command rewrites the files in place.

Step 6: Add to CI

Install the three tools on the runner, then run a dry run. Review the report before you commit optimized files.

- name: Check asset sizes
  run: dart run monorepo_toolkit assets optimize --dry-run

Key Customization Points

Customization	Where to Change
PNG level and JPEG quality	png.level and jpeg.quality in asset_optimizer.yaml
Which folders to scan	paths in asset_optimizer.yaml
Skip files	ignore in asset_optimizer.yaml
Turn a format off	enabled: false for that format

Next Steps

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