[Flutter] FlutterGenの導入手順とハマりポイントまとめ(2025年版)

2025.10.07
 はじめにこんにちは。リテールアプリ共創部所属、iOSエンジニアの haruka です。

秋といえば栗。モンブラン、栗ごはん、甘露煮……食欲に負けたくないけど、栗シーズンは満喫したい。人生って難しいですね。
さて、最近Flutterの学習を始め、iOS以外のモバイル開発にも触れています。

今回は、Flutterでアセット管理を効率化できる便利ツール「FlutterGen」の導入について、実際にハマったポイントを交えながらご紹介します。
 FlutterGenとはFlutterGenは、Flutterプロジェクトにおけるアセット（画像、フォント、カラーなど）を型安全に扱えるようにするコード生成ツールです。
パッケージページ：

https://pub.dev/packages/flutter_gen
通常、画像アセットを使うときは以下のように文字列で指定します。
Widget build(BuildContext context) {
  return Image.asset('assets/images/profile.jpeg');
}
FlutterGenを導入すると、以下のように補完が効く、安全なコードで呼び出せるようになります。
Widget build(BuildContext context) {
  return Assets.images.profile.image();
}
文字列の打ち間違いや、ファイル名の変更によるバグを防げるのが大きなメリットです。
 導入前の状態Flutterの新規プロジェクトを作成したばかりの状態からスタートします。

バージョン指定も含めて、すべてデフォルトの状態です。
pubspec.yaml
environment:
  sdk: ^3.9.0

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8

dev_dependencies:
  flutter_test:
    sdk: flutter
　flutter_lints: ^5.0.0

flutter:
　uses-material-design: true
 必要なパッケージを追加FlutterGenを使うには、以下の2つのパッケージを dev_dependencies に追加する必要があります。
pubspec.yaml
dev_dependencies:
  flutter_test:
    sdk: flutter

  flutter_lints: ^5.0.0
  build_runner: ^2.8.0 # <- 追加
  flutter_gen_runner: ^5.12.0 # <- 追加
（バージョンは2025年10月時点の最新です。必要に応じて調整してください。）
 躓きポイント①：パッケージが2つ必要？「FlutterGenを使いたいだけなのに、なんで2つもパッケージが必要なの？」と最初は戸惑いました。
実は、build_runner は Dart/Flutter におけるコード生成の基盤ツールで、FlutterGenに限らず、Freezed や json_serializable、Riverpod などのコード生成系パッケージでも使用されます。
Dartチームによってメンテナンスされているため、安心して利用できます。
パッケージページ：

https://pub.dev/packages/build_runner
依存関係を追加したら、以下のコマンドでインストールを行います。
flutter pub get
成功すると、以下のようなログが表示されます。

 アセットフォルダの作成と登録次に、Flutterにアセットフォルダを認識させるために、pubspec.yaml に以下を追記します。
pubspec.yaml
flutter:
  uses-material-design: true

  assets: # <- 追加
    - assets/images/ # <- 追加
ファイル単位での指定も可能です。
pubspec.yaml
flutter:  
  assets:
    - assets/images/my_icon.png
    - assets/images/home_icon.png
 躓きポイント②：フォルダは自動で作られないFlutterの公式ドキュメントでも記載されている通り、アセットフォルダ（例：assets/images）は手動で作成する必要があります。
FlutterGenを使っても、フォルダの自動生成は行われません。
最初は「よく使われるフォルダ構成だから、FlutterGenが自動で作ってくれるのでは？」と期待してしまいましたが、結論としては手動で作成・登録が必要です。
また、pubspec.yaml にアセットを登録したにもかかわらず、フォルダが存在しない場合は以下のようなエラーが出ます。

このエラーが出た場合は、プロジェクト内に assets/images/ フォルダを作成しましょう。

 コードを生成する画像ファイルを assets/images/ に追加したら、以下のコマンドでコードを生成します。
dart run build_runner build
成功すると、lib/gen/assets.gen.dart が生成されます。

 出力先のカスタマイズ出力先はデフォルトで lib/gen/ ですが、pubspec.yaml に flutter_gen の設定を追加することで変更可能です。
pubspec.yaml
flutter:
  uses-material-design: true
  assets:
    - assets/images/

flutter_gen: # <- 追加
  output: lib/gen/ # <- 任意のパスに変更可能
また、build.yaml に設定を記述することもできます。

この場合、pubspec.yaml より優先されます。
例：
build.yaml
targets:
  $default:
    builders:
      flutter_gen_runner:
        options:
          output: lib/gen/ # <- 任意のパスに変更可能
 使い方コード生成が完了すると、以下のようにアセットを呼び出せるようになります。
Widget build(BuildContext context) {
  return Assets.images.appIcon768.image();
}
補完も効くので、開発体験がとても快適になります。
 おまけ：対応しているアセットの種類FlutterGenは、Flutterがサポートする以下のようなファイル形式に対応しています。
画像：JPEG, PNG, GIF, WebP, BMP, WBMP など

フォント：.ttf など

カラー： .xml など(Androidスタイル)
注意点：
GIF / WebP のアニメーション情報（フレーム数、duration 等）はデフォルトでは解析されません。詳細を含めたい場合は images.parse_animation: true を有効にする必要があります（ただし生成時間が増加します）。
SVGやLottieなどの特殊形式は、flutter_svg や lottie などの外部パッケージとの統合設定が必要です。
 終わりにFlutterGenの導入はとても便利ですが、初めて使うときはちょっとした落とし穴もあります。
必要なパッケージが2つある（flutter_gen_runner + build_runner）
アセットフォルダは手動で作成・登録が必要
コード生成にはコマンド実行が必要
それでも、型安全なアセット管理やIDE補完の恩恵は非常に大きく、導入する価値は十分にあります。

FlutterGen、ぜひ活用してみてください！