![[Flutter] FlutterGenの導入手順とハマりポイントまとめ(2025年版)](https://devio2024-media.developers.io/image/upload/f_auto,q_auto,w_3840/v1759820313/user-gen-eyecatch/ybvlw1sxuizeso8zu910.png)
[Flutter] FlutterGenの導入手順とハマりポイントまとめ(2025年版)
はじめに
こんにちは。リテールアプリ共創部所属、iOSエンジニアの haruka です。
秋といえば栗。モンブラン、栗ごはん、甘露煮……食欲に負けたくないけど、栗シーズンは満喫したい。人生って難しいですね。
さて、最近Flutterの学習を始め、iOS以外のモバイル開発にも触れています。
今回は、Flutterでアセット管理を効率化できる便利ツール「FlutterGen」の導入について、実際にハマったポイントを交えながらご紹介します。
FlutterGenとは
FlutterGenは、Flutterプロジェクトにおけるアセット(画像、フォント、カラーなど)を型安全に扱えるようにするコード生成ツールです。
パッケージページ:
通常、画像アセットを使うときは以下のように文字列で指定します。
Widget build(BuildContext context) {
return Image.asset('assets/images/profile.jpeg');
}
FlutterGenを導入すると、以下のように補完が効く、安全なコードで呼び出せるようになります。
Widget build(BuildContext context) {
return Assets.images.profile.image();
}
文字列の打ち間違いや、ファイル名の変更によるバグを防げるのが大きなメリットです。
導入前の状態
Flutterの新規プロジェクトを作成したばかりの状態からスタートします。
バージョン指定も含めて、すべてデフォルトの状態です。
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
に追加する必要があります。
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チームによってメンテナンスされているため、安心して利用できます。
パッケージページ:
依存関係を追加したら、以下のコマンドでインストールを行います。
flutter pub get
成功すると、以下のようなログが表示されます。
アセットフォルダの作成と登録
次に、Flutterにアセットフォルダを認識させるために、pubspec.yaml
に以下を追記します。
flutter:
uses-material-design: true
assets: # <- 追加
- assets/images/ # <- 追加
ファイル単位での指定も可能です。
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
の設定を追加することで変更可能です。
flutter:
uses-material-design: true
assets:
- assets/images/
flutter_gen: # <- 追加
output: lib/gen/ # <- 任意のパスに変更可能
また、build.yaml
に設定を記述することもできます。
この場合、pubspec.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、ぜひ活用してみてください!