How to generate type-safe asset enums in Flutter

Docs/Tutorials/asset_generator

Free Reference for asset_generator: every variable, option and package it generates. Command: archipelago generate asset_generator

Add the asset-gen command, write asset_generator.yaml, generate typed enums from your asset folders, and use them in widgets.

What you'll learn

• Adding the asset-gen command to your monorepo toolkit
• Writing the asset_generator.yaml config
• Generating typed asset enums from your asset folders
• Using the enums in widgets

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• monorepo_toolkit already generated at devtools/
• An asset package built from the flutter_asset brick (see Flutter Asset Package)

Step 1: Generate the Asset Generator Command

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

archipelago generate asset_generator

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_generator --config asset_gen_config.json

Step 2: Understand the Generated Structure

The brick adds a script package and registers AssetGenCommand in the toolkit.

devtools/
└── scripts/
    └── asset_generator/
        ├── example/asset_generator.yaml    # Config schema reference
        └── lib/src/
            ├── commands/                   # asset-gen and its generate subcommand
            ├── models/
            └── services/asset_scanner_service.dart

Step 3: Write the Config

Put asset_generator.yaml next to the pubspec.yaml of the package that owns your assets. Copy devtools/scripts/asset_generator/example/asset_generator.yaml as a start.

assets_path: assets
output_path: lib/src/generated
prefix: App
package_name: app_asset
asset_core_import: package:asset_core/asset_core.dart
icon_categories: [actions, arrows, communication]

Set prefix to the prefix you used for asset_core. A mismatch produces code that points at types that do not exist.

Step 4: Generate the Enums

dart run monorepo_toolkit asset-gen generate

The command finds the one package that has an asset_generator.yaml. Pass --package packages/app_asset when there is more than one. Pass --dry-run to preview.

Each category becomes an enum. Icons land in lib/src/generated/icons/<category>_icons.dart. Other categories stay flat. A generated.dart barrel exports everything.

Some details:

• Lottie .json and .lottie files both work. If both exist for one name, the enum points at the .lottie.
• A _dark file next to an asset becomes its darkPath.
• .riv files are skipped with a warning.

Step 5: Use the Enums

// Before: a string that can drift
SvgPicture.asset('assets/icons/actions/copy.svg');

// After: a typed value
const icon = AppActionsIcons.copy;

Use the UI kit asset widgets to load an enum value. See Flutter UI Kit.

Key Customization Points

Customization	Where to Change
Asset folder and output folder	assets_path and output_path in asset_generator.yaml
Icon categories	icon_categories in asset_generator.yaml
Class prefix	prefix in asset_generator.yaml

Next Steps

• Generate an asset package to hold your assets
• Optimize assets before you generate enums