How to set up a type-safe asset package in Flutter

Docs/Tutorials/flutter_asset

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

Generate the asset packages, understand the split between asset_core and your asset package, add SVG icons, Lottie files and logos, and regenerate the enums.

What you'll learn

• Generating the asset packages
• Understanding the split between asset_core and your asset package
• Adding SVG icons, Lottie animations and logos
• Regenerating the typed enums

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

New projects already include this brick.

Step 1: Generate the Asset Package

archipelago generate flutter_asset

The prompts are:

• appName: your app name, for example MyApp
• prefix: the prefix for asset class names
• isForMonorepo: leave this as true
• includeGenerated: false keeps generated files out of git

Or use a config file:

{
  "appName": "MyApp",
  "prefix": "App",
  "isForMonorepo": true,
  "includeGenerated": false
}

archipelago generate flutter_asset --config asset_config.json

Step 2: Understand the Generated Structure

The brick creates two packages in packages/:

packages/
├── asset_core/                    # Pure Dart contracts, no Flutter dependency
│   └── lib/src/
│       ├── {prefix}_asset.dart
│       ├── {prefix}_asset_type.dart
│       └── contracts/             # Icon, animation, illustration and logo contracts
└── my_app_asset/
    ├── lib/src/generated/         # Typed enums
    │   ├── icons/                 # One file per category, such as actions_icons.dart
    │   ├── animations.dart
    │   └── logos.dart
    ├── assets/
    │   ├── icons/                 # SVG icons in category folders
    │   ├── animations/            # Lottie .json or .lottie files
    │   └── logos/
    └── asset_generator.yaml       # Config for the asset-gen command

asset_core has no Flutter dependency. Business logic and tests can use the contracts without it.

Step 3: Add Assets and Regenerate

Drop files into the assets/ folders. Then regenerate the enums:

dart run monorepo_toolkit asset-gen generate

This needs the asset_generator brick. The generated asset_generator.yaml already holds the right prefix and package name.

Step 4: Use Assets in Features

Each asset is an enum value that implements a contract:

import 'package:my_app_asset/my_app_asset.dart';

const copyIcon = AppActionsIcons.copy;

Load an enum value with the asset widgets from the UI kit. They read data and defaultSemanticLabel from the contract. See Flutter UI Kit.

Icons come in sizes through AppIconAsset.sizeSmall (16), sizeMedium (24) and sizeLarge (32).

Key Customization Points

Customization	Where to Change
Add an icon category	A new folder under assets/icons/, then list it in icon_categories in asset_generator.yaml
Class name prefix	The prefix variable at generation
Track generated files in git	includeGenerated: true at generation
Dark variants	Add a name_dark.svg file next to name.svg

Next Steps

• Set up asset generation for automated enum creation
• Optimize assets to reduce app bundle size
• Generate a UI Kit that uses these assets