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

[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 にアセットを登録したにもかかわらず、フォルダが存在しない場合は以下のようなエラーが出ます。
"The asset directory 'assets/images/' doesn't exist.\nTry creating the directory or fixing the path to the directory."

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

コードを生成する

画像ファイルを assets/images/ に追加したら、以下のコマンドでコードを生成します。

			
			dart run build_runner build

		

成功すると、lib/gen/assets.gen.dart が生成されます。
assets.gen.dart

出力先のカスタマイズ

出力先はデフォルトで lib/gen/ ですが、pubspec.yamlflutter_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_svglottie などの外部パッケージとの統合設定が必要です。

終わりに

FlutterGenの導入はとても便利ですが、初めて使うときはちょっとした落とし穴もあります。

  • 必要なパッケージが2つある(flutter_gen_runner + build_runner)
  • アセットフォルダは手動で作成・登録が必要
  • コード生成にはコマンド実行が必要

それでも、型安全なアセット管理やIDE補完の恩恵は非常に大きく、導入する価値は十分にあります。
FlutterGen、ぜひ活用してみてください!

この記事をシェアする

FacebookHatena blogX

関連記事

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