build.yaml Reference#

builders:              # Declare Builder implementations
post_process_builders: # Declare PostProcessBuilder implementations
targets:               # Configure which sources each builder runs on
global_options:        # Override builder options globally (in consuming packages)
additional_public_assets: []  # Extra assets to expose publicly from this package

builders:
  my_builder:
    # Required: Dart import for the builder factory
    import: "package:my_package/builder.dart"

    # Required: List of top-level function names matching BuilderFactory typedef
    builder_factories: ["myBuilder"]

    # Required: Map from input extension(s) to output extension(s)
    # See patterns below
    build_extensions: {".dart": [".g.dart"]}

    # When to apply this builder automatically.
    # Options: none | dependents | allPackages | rootPackage
    # Default: none
    auto_apply: dependents

    # Where generated files go.
    # cache: in build cache (invisible to user, default for source_gen part builders)
    # source: written to disk alongside source files (like dart_mappable's .mapper.dart)
    # Default: cache
    build_to: cache

    # Whether this builder is "lazy" — only runs if its output is needed
    # Default: false
    is_optional: false

    # Extensions that MUST exist before this builder runs (for ordering)
    # The builder still runs even if required_inputs aren't present —
    # it's purely for ordering, not filtering
    required_inputs: [".freezed.dart"]

    # Builder keys that should run AFTER this builder
    # Format: "package_name|builder_name"
    runs_before: ["other_package|other_builder"]

    # Builders that should be applied when this builder is applied
    # Most common: tells build_runner to also run source_gen's combining_builder
    # which merges .g.part files into a single .g.dart
    applies_builders: ["source_gen|combining_builder"]

    # Default configuration for consuming packages
    defaults:
      generate_for:
        - "lib/**"
        - "!lib/**/*.g.dart"
      options:
        some_option: value
      dev_options:
        verbose: true
      release_options:
        verbose: false

# Simple suffix — matches any file with that extension
build_extensions: {".dart": [".g.dart"]}

# Multiple outputs from one input
build_extensions: {".dart": [".mapper.dart", ".init.dart"]}

# Multiple input extensions
build_extensions:
  ".dart": [".g.dart"]
  ".json": [".dart"]

# Path-anchored (^ prefix) — only this exact path
build_extensions: {"^pubspec.yaml": ["lib/src/pubspec.g.dart"]}

# Capture group ({{}}) — captures part of the path
build_extensions: {"^assets/{{}}.json": ["lib/generated/{{}}.dart"]}
# assets/users.json → lib/generated/users.dart

# Package-level ($package$) — runs exactly once per package
build_extensions: {r"$package$": ["lib/generated/all_mappers.dart"]}

post_process_builders:
  my_post_builder:
    import: "package:my_package/builder.dart"

    # Only ONE factory function (not a list, unlike builders:)
    builder_factory: "myPostBuilder"

    # Extensions of files to process
    input_extensions: [".dart"]

    # cache or source
    build_to: cache

    defaults:
      generate_for: ["lib/**"]
      options: {}

targets:
  # $default is the standard target for a package's lib/ sources
  $default:
    # Glob patterns for files included in this target
    # Exclusions start with !
    sources:
      - "lib/**"
      - "test/**"
      - "!lib/**/*.g.dart"

    # Whether build_runner should auto-apply builders from dependencies
    # Default: true
    auto_apply_builders: true

    # Per-builder configuration overrides
    builders:
      # Key format: "package_name|builder_name"
      "source_gen|combining_builder":
        options:
          ignore_for_file:
            - "lines_longer_than_80_chars"

      "json_serializable|json_serializable":
        # Enable or disable this builder for this target
        enabled: true

        # Glob patterns (relative to package root) for which inputs this builder runs on
        generate_for:
          - "lib/src/**"
          - "test/**"
          # Exclusions:
          - "!lib/src/generated/**"

        # Options passed to the builder (builder reads from BuilderOptions.config)
        options:
          field_rename: snake
          explicit_to_json: true

        # Options only in dev builds (dart pub get vs dart pub get --no-precompile)
        dev_options:
          checked: true

        # Options only in release builds
        release_options:
          checked: false

  # You can define multiple targets (unusual but possible)
  my_tests:
    sources: ["test/**"]
    builders:
      "my_package|my_builder":
        enabled: true

global_options:
  "json_serializable|json_serializable":
    options:
      field_rename: snake
      explicit_to_json: true
    runs_before: []

builders:
  json_serializable:
    import: "package:json_serializable/builder.dart"
    builder_factories: ["jsonSerializable"]
    build_extensions: {".dart": ["json_serializable.g.part"]}
    auto_apply: dependents
    build_to: cache
    applies_builders: ["source_gen|combining_builder"]

builders:
  retrofit_generator:
    import: "package:retrofit_generator/retrofit_generator.dart"
    builder_factories: ["retrofitBuilder"]
    build_extensions: { ".dart": [".retrofit.g.part"] }
    auto_apply: dependents
    build_to: cache
    applies_builders: ["source_gen|combining_builder"]

builders:
  dart_mappable_builder:
    import: "package:dart_mappable_builder/dart_mappable_builder.dart"
    builder_factories: [ "buildMappable" ]
    build_extensions: { ".dart": [ ".mapper.dart", ".init.dart" ] }
    required_inputs: [".freezed.dart"]
    auto_apply: dependents
    build_to: source

# In the app that uses your generator
targets:
  $default:
    builders:
      "my_generator|my_builder":
        options:
          output_prefix: "_generated"
        generate_for:
          - "lib/models/**"