FlutterGen

FlutterGen supports dart pub workspaces. To use it, run build_runner from the workspace root. Ensure each workspace member that requires generation has resolution: workspace in its pubspec.yaml.

Workspace Root Configuration:

environment:
  sdk: ^3.7.0

workspace:
  - packages/app

Member Package Configuration (packages/app/pubspec.yaml):

name: app
resolution: workspace

dev_dependencies:
  flutter_gen_runner:
  build_runner: ^2.12.0

Execution: Run the build from the root using the --workspace flag:

dart run build_runner build --workspace

Note: If you manually removed generated files while .dart_tool/build still exists, run dart run build_runner clean from the workspace root before rebuilding to ensure a reliable incremental build.

To change the launch screen image in an iOS Flutter project, you can either replace the image files directly in the filesystem or use Xcode.

Method 1: Filesystem replacement Replace the existing image files located in the ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.

Method 2: Using Xcode

1. Open the iOS workspace using open ios/Runner.xcworkspace.
2. In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
3. Drag and drop your desired images into the asset catalog.

To integrate FlutterGen into your Flutter project's build pipeline, add build_runner and flutter_gen_runner to your dev_dependencies. Note that flutter_gen_runner requires build_runner >= 2.12.0 because it uses post-process builders with build_to: source.

1. Update pubspec.yaml:

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

2. Run flutter pub get.
3. Generate files using: dart run build_runner build.

Use the official setup action in your CI workflows for macOS and Linux:

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

To run the sample project provided in the repository, you must first bootstrap the monorepo using Melos to ensure all package dependencies and links are correctly established.

cd ../flutter_gen
melos bootstrap

When working in a pub workspace, you can generate asset accessors for all packages simultaneously from the workspace root using the build_runner build --workspace command.

Generated files are typically written to the lib/gen/ directory of each package. For example:

• packages/<package_name>/lib/gen/assets.gen.dart

dart run build_runner build --workspace

You can install the fluttergen CLI tool directly using several package managers:

Pub Global (macOS, Linux, Windows):

dart pub global activate flutter_gen

Homebrew (macOS, Linux):

brew install FlutterGen/tap/fluttergen

asdf (macOS, Linux):

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

asdf install fluttergen latest

To set up and run the sample project provided in the repository, you must first bootstrap the workspace using Melos. This ensures all package dependencies within the monorepo are correctly linked.

Navigate to the root of the flutter_gen repository and run the bootstrap command.

cd ../flutter_gen
melos bootstrap

FlutterGen provides specialized integrations for popular asset types to provide helper methods instead of just returning file paths.

Note for Lottie: When using .lottie or .tgs files, you must provide a custom decoder via the decoder parameter in your code as per the lottie package documentation.

flutter_gen:
  integrations:
    flutter_svg: true
    rive: true
    lottie: true

FlutterGen generates a fonts.gen.dart file based on the flutter: fonts: configuration in your pubspec.yaml. This provides a type-safe FontFamily class.

To support fonts used in a package, enable package_parameter_enabled under flutter_gen > fonts > outputs.

flutter:
  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf

flutter_gen:
  fonts:
    outputs:
      package_parameter_enabled: true

To use FlutterGen in a Dart/Flutter pub workspace, ensure your environment meets the version requirements and use the --workspace flag with build_runner.

Version Requirements

• Dart SDK: >=3.7.0
• build_runner: >=2.12.0 (Required because FlutterGen uses post-process builders with build_to: source).

Installation and Generation

1. Navigate to your workspace root.
2. Fetch dependencies:

   flutter pub get

3. Run the generation process. It is highly recommended to run clean first to ensure all generated files are recreated, as incremental builds might skip missing files due to the post-process builder model:

   dart run build_runner clean
   dart run build_runner build --workspace

cd examples/example_workspace
flutter pub get

dart run build_runner clean
dart run build_runner build --workspace

You can enrich generated asset classes with extra metadata at build time.

• parse_metadata: true: Adds a nullable size field to image-based assets. This allows accessing the asset's dimensions at runtime without manual parsing.
• parse_animation: true: Automatically parses animation details (frames, duration, etc.) for GIF and WebP files. Note: This significantly increases generation time and implies parse_metadata: true is also enabled.

flutter_gen:
  parse_metadata: true
  images:
    parse_animation: true