Introduction

In large-scale Flutter apps, a multi-module structure promotes separation of concerns, parallel development, and faster CI/CD workflows. When combining modules with code generation, build_runner (aka build runner) becomes indispensable. This tutorial dives deep into setting up a modular Flutter workspace, configuring code generation with build_runner, and optimizing your build pipeline for productivity and maintainability.

Module Architecture Setup

1. Workspace layout
   • /packages
   – core (shared utilities, models)
   – feature_user (user-related UI, logic)
   – feature_payment (payment flows)
   • /app (Flutter app entrypoint)

2. Declaring path dependencies
   In each module’s pubspec.yaml, reference shared packages via relative paths. For example, feature_user depends on core:

dependencies:
  flutter:
    sdk: flutter
  core:
    path

3. Isolating build configurations
   Each module that uses code generation must include a dev_dependency on build_runner and any specific builders (json_serializable, injectable, freezed, etc.). In core’s pubspec.yaml:

dev_dependencies:
  build_runner: ^2.3.0
  json_serializable

Integrating build_runner Code Generation

1. Defining models in core
   Use json_serializable in core to generate data classes. In lib/models/user.dart:

import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';

@JsonSerializable()
class User {
  final String id, name;
  User({required this.id, required this.name});
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

Run code generation:

cd packages/core
flutter pub run build_runner build --delete-conflicting-outputs

2. Consuming generated code in feature modules. In feature_user, import the core model:

import 'package:core/models/user.dart';

void displayUser(User user) {
  print('User: ${user.name}');
}

Since user.g.dart already exists in core, feature_user doesn’t need to re-run build_runner unless it has its own generated sources.

3. Orchestrating the runner from root
   For a monorepo, invoke build_runner across all modules with a single command. Use a script (e.g., bash, PowerShell) or tools like Melos. Example in root run_codegen.sh:

#!/usr/bin/env bash
set -e
for pkg in packages/*; do
  if grep -q "build_runner" "$pkg/pubspec.yaml"; then
    (cd $pkg && flutter pub run build_runner build --delete-conflicting-outputs)
  fi
done

4. Customizing builders
   Define a build.yaml in modules to override default behaviors, aggregate outputs, or skip files:

targets:
  $default:
    builders:
      json_serializable:
        options:
          explicit_to_json: true
          any_map: true

Best Practices for Multi-Module Projects

Dependency Direction: Always ensure modules depend only “downstream.” Core → feature → app. Avoid cycles.

Caching & CI: Cache build and .dart_tool/build directories between CI runs. Only re-run code generation when relevant files change.

Avoid Duplicated Builders: If multiple modules use the same builder version, align their versions to prevent conflicts. Maintain a shared dev_dependency pattern via a root “tooling” pubspec or via melos workspace constraints.

Isolate Generated Code: Keep generated files in module-local lib/. Avoid spilling generated artifacts across modules to reduce import confusion.

Automate via CI: Integrate flutter pub run build_runner build --delete-conflicting-outputs or watch mode in pre-commit hooks or CI pipelines. This enforces up-to-date generated sources and prevents stale code.

Vibe Studio

Vibe Studio, powered by Steve’s advanced AI agents, is a revolutionary no-code, conversational platform that empowers users to quickly and efficiently create full-stack Flutter applications integrated seamlessly with Firebase backend services. Ideal for solo founders, startups, and agile engineering teams, Vibe Studio allows users to visually manage and deploy Flutter apps, greatly accelerating the development process. The intuitive conversational interface simplifies complex development tasks, making app creation accessible even for non-coders.

Conclusion

With a well-structured multi-module architecture and build_runner-driven code generation, you gain modularity, clear separation of concerns, and reproducible builds. Whether you’re using json_serializable for models, injectable for dependency injection, or building custom source_gen builders, this setup scales gracefully.