asset_generator Free

Docs/Bricks/asset_generator

Tier

Freeversion 1.2.5

Command

archipelago generate asset_generator

Generates

• devtools/scripts/asset_generator

Depends on

monorepo_toolkitgenerate these first

Tutorial

Step-by-step: add asset_generator to a project

Type-safe asset enum generation from directory structure — scans an assets/ tree and writes <Prefix>AssetData/<Prefix>IconAsset enums plus barrels that match asset_core's prefix-templated contracts. Adds the asset-gen command to the base monorepo_toolkit.

Variables

Variable	Type	Default	Description
appName	string	MyApp	The name of your application
isForMonorepo	boolean	true	Whether this is being generated as part of a monorepo

Install

Interactive

archipelago generate asset_generator

Non-interactive (CI)

archipelago generate asset_generator --config my_config.json

Requires monorepo_toolkit already installed — post_gen adds this script as a path dependency and injects AssetGenCommand() into command_runner.dart's free-command list. It also writes a corrected example/asset_generator.yaml into the target monorepo's root example/ directory.

Config Template

{
  "@appName": "The name of your application",
  "appName": "MyApp",
  "@isForMonorepo": "Whether this is being generated as part of a monorepo",
  "isForMonorepo": true
}

Generated Structure

devtools/
└── scripts/
    └── asset_generator/
        ├── example/
        │   └── asset_generator.yaml               # Config schema reference
        ├── lib/
        │   ├── asset_generator.dart
        │   └── src/
        │       ├── commands/
        │       │   ├── asset_gen_command.dart     # `asset-gen` (parent)
        │       │   └── generate_command.dart      # `generate` (subcommand)
        │       ├── models/
        │       │   ├── asset_generator_config.dart
        │       │   └── discovered_asset.dart
        │       └── services/
        │           └── asset_scanner_service.dart
        ├── test/
        │   ├── asset_scanner_service_test.dart    # Since 1.2.0
        │   └── fixtures/pulse.lottie              # Small dotLottie fixture
        └── pubspec.yaml

Public API / Usage

Place a config file (schema below) at the root of the package that owns your assets, next to its pubspec.yaml:

# <asset-owning-package>/asset_generator.yaml
assets_path: assets                                   # relative to this package
output_path: lib/src/generated
prefix: App                                           # must match asset_core's <Prefix>IconAsset etc.
package_name: app_asset                                # the `package:` assets load from
asset_core_import: package:asset_core/asset_core.dart
icon_categories: [actions, arrows, communication, ...] # subdirs under assets/icons/

Then run:

# Auto-discovers the asset_generator.yaml-owning package in the workspace
dart run devtools/monorepo_toolkit/bin/monorepo_toolkit.dart asset-gen generate

# Point at a specific package explicitly
dart run devtools/monorepo_toolkit/bin/monorepo_toolkit.dart asset-gen generate --package packages/app_asset

# Preview without writing
dart run devtools/monorepo_toolkit/bin/monorepo_toolkit.dart asset-gen generate --dry-run

Icon categories write to <output>/icons/<category>_icons.dart plus an alphabetical <output>/icons/icons.dart barrel; non-icon categories (animations, logos, illustrations) stay flat at <output>/<category>.dart; a top-level <output>/generated.dart barrel exports every category actually written. Scanning order is deterministic (alphabetical). .riv (Rive) assets are skipped with a logged warning — asset_core's asset-type model has no Rive mapping yet.

Generated enum shape

Since 1.2.1, each enum uses a Dart 3.13 primary constructor. The private _darkFilename field is emitted only when an asset in the group has a _dark variant:

// No dark variants in the group
enum AppActionsIcons(this.filename) implements AppIconAsset {
  copy('copy.svg'),
  // ...
  String? get darkPath => null;
}

// At least one dark variant in the group
enum AppLogos(this.filename, {required this.type, this._darkFilename})
    implements AppLogoAsset {
  banuaCoder(
    'banua_coder.svg',
    type: AppAssetType.svg,
    darkFilename: 'banua_coder_dark.svg',
  );

  final String? _darkFilename;

  String? get darkPath =>
      _darkFilename != null ? '$_basePath/$_darkFilename' : null;
  // ...
}

Before 1.2.1 every enum had a separate const constructor and an always-present _darkFilename, which the analyzer flagged as unused_element_parameter in groups with no dark variants. The public API (filename, type, path, darkPath, data) is the same in both shapes, so no app code changes. Run asset-gen generate again to update committed generated files.

Lottie: .json and .lottie

Since 1.2.0, animations can be raw Lottie .json or .lottie (a dotLottie zip of manifest.json plus animations/<id>.json). Both generate a <Prefix>AssetType.lottie member. A .lottie is usually 85-90% smaller than the same .json.

If foo.json and foo.lottie are in the same directory, the generator emits one foo member that points at foo.lottie. The .json stays on disk as the design source and is not bundled twice. A dark variant pairs by the winning file's extension, so foo.lottie pairs with foo_dark.lottie.

No rendering change is needed. Lottie.asset() (used by <Prefix>AssetWidget and LottieCache in flutter_ui_kit) checks the file's first bytes for the zip signature and decodes either format.

DI & Wiring

Not applicable — pure Dart CLI command; the generated enums are consumed by whatever package declares them, not registered in any DI container by this tool.

Dependencies

asset_generator script package: path, yaml, plus shared_scripts (workspace path dependency, provides CliLogger/MonorepoFinder). Dev: test.

Platform Setup

None required — pure Dart CLI tool.

Limitations

• The prefix in asset_generator.yaml must match the prefix your asset_core package (from flutter_asset) was actually generated with — a mismatch produces code that references non-existent types.
• If you hand-wrote a config against the pre-1.1.0 schema (assets_dir/output_dir/package/nested categories:), those keys were never actually read by AssetGeneratorConfig.fromYaml even then — there is nothing to migrate, since no config ever worked against the old schema. Use the fields shown above.
• --package auto-discovery only works if exactly one asset_generator.yaml exists in the workspace; otherwise pass --package explicitly.

Changelog

Run archipelago brick info asset_generator to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.