build_runner によるコード生成

JSONの解析のように、繰り返しの多い定型コードがあります。Code generationを使うと、アノテーションからそのコードを自動生成でき、正確さと開発速度を保てます。⚙️

build_runnerは、プロジェクト上でコードジェネレーターを実行するDartのツールです。ソースファイルを読み込み、アノテーションを見つけて、新しいファイルを生成します。

build_runner はビルド時に実行され、アプリと一緒に配布されることはないため、pubspec.yaml の dev_dependencies に追加します。

ジェネレーターは同じディレクトリにある別のファイルへ書き込みます。慣例として名前の末尾が .g.dart になる part ディレクティブで、そのファイルを参照します。

一度だけコード生成を行うには、build コマンドを実行します。コードを解析し、すべての .g.dart ファイルを作成または更新します。

開発中は、watch モードにすると保存するたびに自動で再生成されます。手動で再実行しなくても、生成ファイルを常に最新の状態に保てます。

出力ファイルが古いファイルと競合する場合は、--delete-conflicting-outputs を追加します。古い生成ファイルを削除して、最新のビルドを成功させます。

ジェネレーターが処理するのは、annotate した宣言だけです。アノテーションによって、どのクラスを処理し、どのコードを生成するかをビルダーに伝えます。

すべての .g.dart ファイルを read-only として扱ってください。次回のビルドで変更内容が上書きされるため、代わりにソースコードとアノテーションを編集します。

生成ファイルをコミットするか、.gitignore に追加して CI で再生成するかは、チームによって異なります。どちらを選ぶ場合も、方針を決めて一貫して運用してください。

json_serializable や freezed など、多くのパッケージが build_runner と連携します。これらは1つの builder パイプラインを共有するため、1回のコマンドですべてを実行できます。

ファイルを保存するたびにコードを再生成するコマンドはどれですか？

build_runner はアノテーションを生成された .g.dart ファイルに変換します。dev_dependencies に追加し、build または watch を実行して、出力ファイルは決して編集しないでください。🎉