The builders

spring_core_dart_generator registers nine builders in its build.yaml. Eight of them apply by themselves to every package that depends on the generator; spring_properties is off until a package turns it on. Each builder checks first whether the package needs it, and writes nothing otherwise, so a pure Dart server never gets Flutter files and a Flutter app without a theme gets no theme keys.

Why several builders

A build_runner builder declares its inputs and outputs in advance. The generator's outputs are of different shapes:

Each shape is a builder of its own. Splitting them also lets a package switch off what it does not use.

Overview

Builder Input Writes Runs when
spring_core_dart every .dart file of lib/, bin/, test/, example/ <root>/spring_gen/<path>.spring.dart the file has @ComponentScan or @SpringBootApplication
spring_properties every .dart file of lib/ lib/spring_gen/<path>.spring.dart a package enables it (off by default)
spring_test test/**_test.dart test/spring_gen/<name>.test.spring.dart the file has @SpringBootTest or @DataTest classes
spring_prefetch the package lib/resources/spring_gen/prefetch/resources.json spring.resources.prefetch.locations is set
spring_search_index the package lib/resources/spring_gen/search/<language>.json spring.search.markdown is set
spring_json_schemas the package lib/spring_gen/json_schemas.spring.classes.dart spring.json.schemas is set
spring_metadata the package lib/spring_gen/spring_metadata.json lib/ or bin/ has Spring code
spring_flutter_keys the package lib/spring_gen/theme.spring.keys.dart, lib/spring_gen/messages.spring.keys.dart the package depends on spring_boot_starter_flutter and has theme properties or message files
spring_flutter_web the package web_dev_config.yaml (not declared) spring.flutter.web.dev-server.* or spring.flutter.security.web.mode is set
spring_flutter_page_loader the package a block of web/index.html (not declared) the package depends on spring_boot_starter_flutter and has web/index.html
spring_flutter_seo the package pages, sitemap.xml, robots.txt, llms.txt in web/ (not declared) spring.flutter.web.seo.enabled is true and web/index.html exists
spring_flutter_deep_links the package blocks of Info.plist, Runner.entitlements, AndroidManifest.xml; domain files (not declared) spring.flutter.navigation.deep-links.* is set

In build.yaml, a builder is named with the package first: spring_core_dart_generator:spring_core_dart.

spring_core_dart

The main builder. It writes the bean modules and the application.

Option Values Default Page
aop_proxies all, interfaces, none all AOP proxies
aop_prune true, false true AOP proxies
aop_defer true, false false AOP proxies
dart_defines_exclude a list of property name prefixes [] --dart-define keys

A wrong value (an unknown aop_proxies mode, a non-boolean, a wildcard in dart_defines_exclude) fails the build with an ArgumentError. All options are on Options.

# build.yaml of your package
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          aop_proxies: interfaces
          dart_defines_exclude: [spring.flutter.theme]

spring_properties

The main builder again, limited to lib/ and placed in a phase of its own, before spring_core_dart (runs_before).

# build.yaml of spring_boot_starter_flutter_security
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        generate_for: [example/**]
      spring_core_dart_generator:spring_properties:
        enabled: true
        generate_for: [lib/src/properties/**]
      spring_core_dart_generator:spring_test:
        enabled: false

Applications do not need it.

spring_test

The test builder. See Tests.

spring_json_schemas

Writes the classes of the JSON Schemas of spring.json.schemas. See JSON Schema classes.

spring_prefetch

Writes the files of spring.resources.prefetch.locations into one file a Flutter web app downloads once. See Downloading them together.

spring_search_index

Writes the search index of spring.search.markdown, so the app reads it instead of building it. See The index the build writes.

spring_metadata

Writes the metadata editors and tools read. See Metadata for editors.

spring_flutter_keys

Writes the typed keys of a Flutter app's configuration: context.theme and context.messages. See Typed keys.

spring_flutter_web

Writes web_dev_config.yaml, the file flutter run reads for the web (Flutter 3.38 and later). See The web dev server.

spring_flutter_page_loader

Writes the page loader of the active theme's splash into web/index.html, so the browser shows the app's look before Flutter starts. See The page loader.

spring_flutter_seo

Writes the pages search engines, link previews and language models read, since a Flutter web app draws on a canvas and its HTML holds no text. See Pages for search engines.

Writes the deep links of an app into its platform files, and the files its domains serve. See Deep links.

Switching a builder off

Use build_runner's enabled setting in the build.yaml of your package (next to pubspec.yaml):

# build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_flutter_seo:
        enabled: false
      spring_core_dart_generator:spring_test:
        enabled: false

To keep a builder but limit the files it looks at, use generate_for:

targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        generate_for: [example/**]

What must stay on

Builder Can it be switched off?
spring_core_dart Not in an application or a package with @ComponentScan modules: your code imports the files it writes. A package written by hand (a starter) may switch it off or limit it to its example.
spring_flutter_keys Not while spring_core_dart runs in a Flutter app with theme properties or message files. The main builder writes the part lines for theme.spring.keys.dart and messages.spring.keys.dart without checking that the files exist (it cannot: they are written in another phase), so without the keys builder the generated library points at missing parts and does not compile.
spring_metadata Yes, but spring_flutter_seo takes the routes from its file, the keys builder of an app finds a library's loader kinds in it, and editors lose completion. Keep it on in a library that declares loader kinds or routes.
spring_json_schemas Yes, but spring.json.schemas then writes no classes, and the main builder no longer gives the module their introspections.
spring_search_index Yes: the app then builds the search index itself, as with spring.search.prebuilt: false.
spring_test Yes, if no test uses @SpringBootTest or @DataTest.
spring_flutter_web, spring_flutter_page_loader, spring_flutter_seo, spring_flutter_deep_links Yes. They write only into files the app owns. A disabled one no longer updates or removes what it wrote before.
spring_properties Off by default.

In Spring (Java)

Spring Boot has two build-time tools that play a similar role: spring-boot-configuration-processor, an annotation processor that writes META-INF/spring-configuration-metadata.json (like spring_metadata), and the Spring AOT engine of the Maven and Gradle plugins, which writes Java source for the bean definitions (like spring_core_dart). The Flutter builders have no counterpart in Spring.

See also