flutter_gen_runner

Readme

The Flutter code generator for your assets, fonts, colors, … — Get rid of all String-based APIs.

Inspired by SwiftGen.

Motivation

Using asset path string directly is not safe.

# pubspec.yaml
flutter:
  assets:
    - assets/images/profile.jpg

❌ Bad
What would happen if you made a typo?

Widget build(BuildContext context) {
  return Image.asset('assets/images/profile.jpeg');
}

// The following assertion was thrown resolving an image codec:
// Unable to load asset: assets/images/profile.jpeg

⭕️ Good
We want to use it safely.

Widget build(BuildContext context) {
  return Assets.images.profile.image();
}

Installation

As a part of build_runner

1. Add build_runner and FlutterGen to your package's pubspec.yaml file:

   environment:
     sdk: ^3.7.0
   
   dev_dependencies:
     build_runner: ^2.12.0
     flutter_gen_runner:
   

   flutter_gen_runner now relies on post-process builders with build_to: source, so build_runner >=2.12.0 is required.

2. Install FlutterGen

   flutter pub get
   

3. Use FlutterGen

   dart run build_runner build
   

Pub workspaces

FlutterGen also supports dart pub workspaces. Run build_runner from the workspace root, and make sure each workspace member that should be built has resolution: workspace in its pubspec.yaml.

# workspace root pubspec.yaml
environment:
  sdk: ^3.7.0

workspace:
  - packages/app

# packages/app/pubspec.yaml
name: app
resolution: workspace

dev_dependencies:
  flutter_gen_runner:
  build_runner: ^2.12.0

dart run build_runner build --workspace

FlutterGen will resolve each package from the active build target instead of the process working directory, so package-local pubspec.yaml configuration and output paths continue to work in workspace builds.

If generated source files were removed manually while .dart_tool/build is still present, run dart run build_runner clean from the workspace root before running build --workspace again. The current post-process builder flow can re-materialize files reliably after a clean build, but a warm incremental build may skip unchanged manifests.

For workspace builds, use Dart >=3.7.0 together with build_runner >=2.12.0.

Pub Global

Works with macOS, Linux and Windows.

dart pub global activate flutter_gen

You might need to set up your path.

Homebrew

Works with macOS and Linux.

brew install FlutterGen/tap/fluttergen

asdf

Works with macOS and Linux. asdf-fluttergen is compatible with mise.

# add plugin
asdf plugin add fluttergen
# or
asdf plugin add fluttergen https://github.com/FlutterGen/asdf-fluttergen.git

# install fluttergen
asdf install fluttergen latest

See also: FlutterGen/asdf-fluttergen

GitHub Actions

Works with macOS and Linux.

- uses: FlutterGen/setup-fluttergen@v1
  with:
    version: ${{ fluttergen_version }}

See also: FlutterGen/setup-fluttergen

Usage

Run fluttergen after the configuration pubspec.yaml.

fluttergen -h

fluttergen -c example/pubspec.yaml

fluttergen --workspace -c pubspec.yaml

Use --workspace to treat the config file as a workspace root pubspec and run generation for each listed workspace member. Without --workspace, the command generates for exactly one package.

When --workspace is enabled, the root pubspec.yaml is used only to discover workspace members from its workspace: section. FlutterGen then switches to each member package and loads that package's own pubspec.yaml and, if present, its local build.yaml.

That means workspace-wide command execution behaves like this:

• Root pubspec.yaml: selects which packages to visit.
• Member pubspec.yaml: provides flutter and flutter_gen configuration.
• Member build.yaml: overrides generator options for that member only.

The --build option is only available in single-package mode. In workspace mode, put any overrides in each package's local build.yaml instead.

Configuration file

FlutterGen generates dart files based on the key flutter and flutter_gen of pubspec.yaml.
Default configuration can be found here.

# pubspec.yaml
# ...

flutter_gen:
  output: lib/gen/ # Optional (default: lib/gen/)
  # line_length: 80 # Optional

  # Optional
  integrations:
    image: true
    flutter_svg: true
    rive: true
    lottie: true

  colors:
    inputs:
      - assets/color/colors.xml

flutter:
  uses-material-design: true
  assets:
    - assets/images/

  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic

build.yaml

When using build_runner, you can also configure generator options in the target build.yaml. These builder options are applied on top of the pubspec.yaml configuration for the current target.

# build.yaml
# ...

targets:
  $default:
    builders:
      flutter_gen_runner: # or flutter_gen
        options:
          output: lib/build_gen/ # Optional (default: lib/gen/)
          line_length: 120 # Optional

Available Parsers

Assets

Following the doc Adding assets and images#Specifying assets to specify assets, then FlutterGen will generate related dart files.
No other specific configuration is required.
Ignore duplicated.

# pubspec.yaml
flutter:
  assets:
    - assets/images/
    - assets/images/chip3/chip.jpg
    - assets/images/chip4/chip.jpg
    - path: assets/images/icons/paint.svg
    - path: assets/images/icons/transformed.svg
      transformers:
        - package: vector_graphics_compiler
    - assets/images/icons/dart@test.svg
    - assets/json/fruits.json
    - assets/flare/Penguin.flr
    - assets/rive/vehicles.riv
    - pictures/ocean_view.jpg

  # Also include assets from deferred components
  # https://docs.flutter.dev/perf/deferred-components
  deferred-components:
    - name: myDeferredComponent
      assets:
        - assets/images/another_image.jps
        - assets/videos/a_large_video.mp4

These configurations will generate assets.gen.dart under the lib/gen/ directory by default.

Flavored assets

Flutter supports Conditionally bundling assets based on flavor. Assets are only available with flavors if specified. flutter_gen will generate the specified flavors for assets regardless the current flavor. The flavors field accessible though .flavors, for example:

print(MyAssets.images.chip4.flavors); // -> {'extern'}

Excluding generating for assets

You can specify flutter_gen > assets > exclude using Glob patterns to exclude particular assets.

flutter_gen:
  assets:
    exclude:
      - folder-your-want-to-exclude/**
      - specified-asset.jpg

See more patterns with the package:glob.

Generate for packages

If you want to generate assets for a package, use package_parameter_enabled under flutter_gen > assets > outputs.

flutter_gen:
  assets:
    outputs:
      package_parameter_enabled: true # <- Add this line.

This would add the package constant to the generated class. For example:

class Assets {
  const Assets._();

  static const String package = 'test';

  static const $AssetsImagesGen images = $AssetsImagesGen();
  static const $AssetsUnknownGen unknown = $AssetsUnknownGen();
}

Then you can use assets with the package implicitly or explicitly:

// Implicit usage for `Image`/`SvgPicture`/`Lottie`.
Widget build(BuildContext context) {
  return Assets.images.icons.paint.svg(
    width: 120,
    height: 120,
  );
}

or

// Explicit usage for `Image`/`SvgPicture`/`Lottie`.
Widget build(BuildContext context) {
  return SvgPicture.asset(
    Assets.images.icons.paint.path,
    package: Assets.package,
    width: 120,
    height: 120,
  );
}

Generate directories path

If you want to generate the path of directories, use directory_path_enabled under flutter_gen > assets > outputs.

flutter_gen:
  assets:
    outputs:
      directory_path_enabled: true # <- Add this line.

This would add the path getter to the generated directory class. For example:

class $AssetsImagesGen {
  const $AssetsImagesGen();

  ///******///

  /// Directory path: assets/images
  String get path => 'assets/images';
}

Including additional metadata

At build time, additional metadata may be included in the generated class, by using the parse_metadata option.

flutter_gen:
  parse_metadata: true # <- Add this line (default: false)

For image based assets, a new nullable size field is added to the generated class. For example:

AssetGenImage get logo => const AssetGenImage(
  'assets/images/logo.png',
  size: Size(209.0, 49.0),
);

Which can now be used at runtime without parsing the information from the actual asset.

Widget build(BuildContext context) {
  return Assets.images.logo.size!.width;
}

You can use parse_animation to generate more animation details. It will automatically parse all animation information for GIF and WebP files, including frames, duration, etc. As this option significantly increases generation time, The option is disabled by default; enabling it will significantly increase the generation elapse.

flutter_gen:
  images:
    parse_animation: true # <- Add this line (default: false)
    # This option implies parse_metadata: true when parsing images.

For GIF and WebP animation, several new nullable field is added to the generated class. For example:

AssetGenImage get animated =>
  const AssetGenImage(
    'assets/images/animated.webp',
    size: Size(209.0, 49.0),
    isAnimation: true,
    duration: Duration(milliseconds: 1000),
    frames: 15,
  );

Usage Example

FlutterGen generates Image class if the asset is Flutter supported image format.

Example results of assets/images/chip.jpg:

• Assets.images.chip is an implementation of AssetImage class.
• Assets.images.chip.image(...) returns Image class.
• Assets.images.chip.provider(...) returns ImageProvider class.
• Assets.images.chip.path just returns the path string.
• Assets.images.chip.values just returns the values list.

Widget build(BuildContext context) {
  return Assets.images.chip.image();
}

Widget build(BuildContext context) {
  return Assets.images.chip.image(
    width: 120,
    height: 120,
    fit: BoxFit.scaleDown,
  );

Widget build(BuildContext context) {
  // Assets.images.chip.path = 'assets/images/chip3/chip3.jpg'
  return Image.asset(Assets.images.chip.path);
}

If you do not want to generate AssetGenImage, set flutter_gen > integrations > image to false.

# pubspec.yaml
flutter_gen:
  integrations:
    image: false

If you are using SVG images with flutter_svg you can use the integration feature. This feature also supports using vector_graphics_compiler transformer and the produced code will use the AssetBytesLoader for such transformed assets.

# pubspec.yaml
flutter_gen:
  integrations:
    flutter_svg: true

flutter:
  assets:
    - assets/images/icons/paint.svg
    - path: assets/images/icons/transformed.svg
      transformers:
        - package: vector_graphics_compiler

Widget build(BuildContext context) {
  return Assets.images.icons.paint.svg(
    width: 120,
    height: 120
  );
}

Available Integrations

Note: For lottie integration with .lottie and .tgs files, you must add a custom decoder via decoder parameter, see lottie's document for more information.

In other cases, the asset is generated as String class.

// If don't use the Integrations.
final svg = SvgPicture.asset(Assets.images.icons.paint);

final json = await rootBundle.loadString(Assets.json.fruits);

FlutterGen also support generating other style of Assets class:

# pubspec.yaml
flutter_gen:
  assets:
    outputs:
      # Assets.imagesChip
      # style: camel-case

      # Assets.images_chip
      # style: snake-case

      # Assets.images.chip (default style)
      # style: dot-delimiter

flutter:
  assets:
    - assets/images/chip.png

The root directory will be omitted if it is either assets or asset.

assets/images/chip3/chip.jpg      => Assets.images.chip3.chip
assets/images/chip4/chip.jpg      => Assets.images.chip4.chip
assets/images/icons/paint.svg     => Assets.images.icons.paint
assets/images/icons/dart@test.svg => Assets.images.icons.dartTest
assets/json/fruits.json           => Assets.json.fruits
pictures/ocean_view.jpg           => Assets.pictures.oceanView

Example of code generated by FlutterGen

Fonts

Just follow the doc Use a custom font to specify fonts, then FlutterGen will generate related dart files.
No other specific configuration is required.
Ignore duplicated.

# pubspec.yaml
flutter:
  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic
    - family: RobotoMono
      fonts:
        - asset: assets/fonts/RobotoMono-Regular.ttf
        - asset: assets/fonts/RobotoMono-Bold.ttf
          weight: 700

These configurations will generate fonts.gen.dart under the lib/gen/ directory by default.

Generate for packages

If you want to generate fonts for a package, use package_parameter_enabled under flutter_gen > fonts > outputs.

flutter_gen:
  fonts:
    outputs:
      package_parameter_enabled: true # <- Add this line.

This would add the package constant to the generated class. For example:

class Fonts {
  Fonts._();

  static const String package = 'test';

  static const String raleway = 'packages/$package/Raleway';
  static const String robotoMono = 'packages/$package/RobotoMono';
}

Usage Example

Text(
  'Hi there, I\'m FlutterGen',
  style: TextStyle(
    fontFamily: FontFamily.robotoMono,
    fontFamilyFallback: const [FontFamily.raleway],
  ),
)

Example of code generated by FlutterGen

Colors

FlutterGen supports generating colors from XML format files.
Ignore duplicated.

# pubspec.yaml
flutter_gen:
  colors:
    inputs:
      - assets/color/colors.xml
      - assets/color/colors2.xml

FlutterGen can generate a Color class based on the name attribute and the color hex value. If the element has the attribute type, then a specially color will be generated.

Currently supported special color types:

• MaterialColor
• MaterialAccentColor

Noticed that there is no official material color generation algorithm. The implementation is based on the mcg project.

<color name="milk_tea">#F5CB84</color>
<color name="cinnamon" type="material">#955E1C</color>
<color name="yellow_ocher" type="material material-accent">#DF9527</color>

These configurations will generate colors.gen.dart under the lib/gen/ directory by default.

Usage Example

Text(
  'Hi there, I\'m FlutterGen',
  style: TextStyle(
    color: ColorName.denim,
  ),

Example of code generated by FlutterGen

Credits

The material color generation implementation is based on mcg and TinyColor.

Issues

Please file FlutterGen specific issues, bugs, or feature requests in our issue tracker.

Plugin issues that are not specific to FlutterGen can be filed in the Flutter issue tracker.

Known Issues

Bad State: No Element when using build_runner

If you get an error message like this:

[SEVERE] flutter_gen_runner:flutter_gen_runner on $package$:

Bad state: No element
[SEVERE] Failed after 16.0s

The you most likely have a customized build.yaml to configure the build runner. In that case, all you have to do is to add the pubspec.yaml as build source to your build.yaml

targets:
  $default:
    sources:
      include:
        - pubspec.yaml # add this line
        - ...

See #268 for the corresponding issue discussion.

Error with internationalization

Please try to remove generate: true in your pubspec.yaml and disable synthetic-package in your l10n.yaml like:

# pubspec.yaml
flutter:
  generate: true <--- ⚠️Remove this line⚠️

# l10n.yaml
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
synthetic-package: false <--- ⚠️Add this line⚠️

Contributing

We are looking for co-developers.

If you wish to contribute a change to any of the existing plugins in this repo, please review our contribution guide and open a pull request.