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:
- one
.spring.dartfile per scanned library (the main builder); - one file per test file (the test builder);
- one file per package (
spring_metadata.json, the typed keys); - files the app owns and edits too (
web/index.html,Info.plist,AndroidManifest.xml,web_dev_config.yaml), which must not be declared as outputs, becausebuild_runnerwould overwrite a hand-written file of that name and delete it when the builder stopped writing it.
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.
- Reads: a
.dartfile oflib/,bin/,test/orexample/. If its text containsComponentScanorSpringBootApplication, the file is resolved, then every library under its scan root, the files oflib/resources/,pubspec.yaml, and (for an application) thelib/spring_auto_configuration.dartof every dependency. - Writes:
<root>/spring_gen/<path>.spring.dart: aBeanModulefor a@ComponentScanvariable, or the whole application for a@SpringBootApplicationmain. - Silent: for every file without either annotation. Such a file is not even resolved.
- Options:
| 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).
- Why it exists: a starter written by hand binds its
@ConfigurationPropertiesclasses through a@ComponentScanlibrary inlib/, and its ownlib/imports the generated module. Its example (generated by the main builder) imports thatlib/. A builder cannot read what another input of its own phase writes, so thelib/part is generated one phase earlier, where the example's step can read it. - Reads and writes: as the main builder, for
lib/only. - Options: the same as
spring_core_dart. - Off by default (
auto_apply: none). A package turns it on withenabled: true, and limits the main builder to its example:
# 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.
- Reads: each
test/<name>_test.dart. If its text containsSpringBootTestorDataTest, it is parsed (not resolved) and its test classes are read. It also looks at the.dartfiles ofbin/andlib/to find the application under test. - Writes:
test/spring_gen/<name>.test.spring.dartwith arunSpringTests()function, which the test'smaincalls. - Silent: for test files without
@SpringBootTestor@DataTestclasses. - Options: none.
spring_json_schemas
Writes the classes of the JSON Schemas of spring.json.schemas. See JSON Schema classes.
- Reads:
spring.json.schemas[n].*(as the app reads it, without a profile), the schemas ofresources:inlib/resources/, and the remote ones (https://,github:), which it downloads at every build and keeps in.dart_tool/spring/json_schemas/. - Writes:
lib/spring_gen/json_schemas.spring.classes.dart, a part of the application's.spring.dartlibrary. The main builder gives the module the introspections of its classes and embeds a remote schema as a resource. - Silent: when
spring.json.schemasis not set. - Options: none.
spring_prefetch
Writes the files of spring.resources.prefetch.locations into one file a Flutter web app downloads once. See Downloading them together.
- Reads:
spring.resources.prefetch.locations(without a profile) and the text files oflib/resources/its globs match. - Writes:
lib/resources/spring_gen/prefetch/resources.json, a line per piece, on disk (no declared outputs). Never embedded; a missingflutter: assets:entry is warned about. - Silent: without locations; the file written before is deleted.
- Options: none.
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.
- Reads:
spring.search.markdown[n].*,spring.search.analyzers.*,spring.search.default-language(without a profile) and the Markdown files of thoseresources:locations, cut and analyzed by the app's ownspring_search_dart: the builder runs itsbin/search_index.dartwith the app's packages (three minutes at most), so the generator does not depend on the search, and a package without it gets nothing. - Writes:
lib/resources/spring_gen/search/<language>.json, one per language, on disk (no declared outputs: the languages are known once the pages are read), deleting those of a language gone. The main builder never embeds them; a Flutter app lists the directory underflutter: assets:, warned about when missing. - Silent: without
spring.search.markdown, withspring.search.prebuilt: falseorspring.search.enabled: false, or for a location outsideresources:. A language whose analyzer is an app's own bean gets no file. - Options: none.
spring_metadata
Writes the metadata editors and tools read. See Metadata for editors.
- Reads: the
.dartfiles oflib/andbin/(generated files left out), andlib/resources/. - Writes:
lib/spring_gen/spring_metadata.json: configuration properties with their descriptions and defaults, beans, profiles, value hints, and for Flutter the theme, the loader kinds and the routes. - Silent: when no file of
lib/orbin/mentions Spring code:ComponentScan,SpringBootApplication,AutoConfigurationModule,ConfigurationProperties, a hand-writtenBeanDefinition<,@Component,@Service,@Configuration,@Bean,@ThemeLoaderKind,@ScreenRouteor@RouteShell. - On errors: like the main builder, it keeps an existing file while the sources have errors.
- Runs before
spring_flutter_seo, which reads the routes from this file. - Options: none.
spring_flutter_keys
Writes the typed keys of a Flutter app's configuration: context.theme and context.messages. See Typed keys.
- Reads: every
.yml,.yamland.propertiesfile oflib/resources/(any profile, any theme), theresources:files thatspring.config.importnames from a dependency, the@ThemeLoaderKindclasses oflib/, and the loader kinds listed in thespring_metadata.jsonof the dependencies. - Writes:
lib/spring_gen/theme.spring.keys.dart(withspring.flutter.theme.*properties) andlib/spring_gen/messages.spring.keys.dart(withmessages*.propertiesfiles). Both arepart ofthe.spring.dartof the package's@SpringBootApplicationlibrary, else of its outermost@ComponentScan. - Silent: when no dependency name in
pubspec.yamlstarts withspring_boot_starter_flutter, or when there are neither theme properties nor message files. If no library has a@ComponentScanor@SpringBootApplication, nothing is written and a warning says why. Unrelated scan roots in one package fail with their names. - Options: none.
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.
- Reads: the config files of
lib/resources/, as the app reads them in a browser (application.*,application-web.*, the active profiles,spring.config.import). - Writes:
web_dev_config.yamlin the package directory. It is not a declared output: the builder only writes or deletes a file that starts with its own header# GENERATED FILE - DO NOT MODIFY BY HAND., and deletes it once the properties are gone. A hand-written file of that name together with the properties fails the build and asks you to remove one. - Silent: unless a config file sets a
spring.flutter.web.dev-server.*key orspring.flutter.security.web.mode. Without one, the config is not even loaded, so it never fails the build of a pure Dart package. - Options: none.
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.
- Reads:
lib/resources/(the theme),web/index.html, and theweb:HTML files of the app's own loader kinds. - Writes: a block between
<!-- spring:loader:start -->and<!-- spring:loader:end -->inweb/index.html. The markers are inserted after<body>when missing; the rest of the file is never touched. The block is rewritten on every build, and removed with its markers when the theme has no splash. - Silent: when the package does not depend on
spring_boot_starter_flutter(any dependency whose name starts with it), or whenweb/index.htmldoes not exist (it is never created). Most of what it cannot use (a loader'sweb:file it cannot read, for example) is a warning, not an error. - Runs before
spring_flutter_seo, whose pages are copies ofweb/index.html. - Options: none.
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.
- Reads:
spring.flutter.web.seo.*(with thewebprofile), the Markdown files oflib/resources/,web/index.html, and the routes inlib/spring_gen/spring_metadata.json. - Writes: into
web/:<path>/index.htmlper page,<path>.md,sitemap.xml,robots.txt,llms.txtandllms-full.txt; the root page intoweb/index.htmlbetweenspring:seomarkers. The files it wrote are listed inweb/.spring-seo, so a page that is gone is deleted on the next build. - Silent: unless
spring.flutter.web.seo.enabledistrueandweb/index.htmlexists (with the property set but no page, it warns). When the property is gone, the pages it wrote before are removed. - Options: none.
spring_flutter_deep_links
Writes the deep links of an app into its platform files, and the files its domains serve. See Deep links.
- Reads:
spring.flutter.navigation.deep-links.*, read per platform with that platform's profiles (iosandmobile,androidandmobile,macosanddesktop). - Writes: blocks between
spring:deep-links:startandspring:deep-links:endinios/Runner/Info.plist,ios/Runner/Runner.entitlements(when it exists),macos/Runner/Info.plistandandroid/app/src/main/AndroidManifest.xml; andapple-app-site-associationandassetlinks.json(intoweb/.well-known/for an app with a web version, elsebuild/spring/well-known/). A block changed by hand fails the build. - Silent: when no config file mentions
deep-links. A block whose properties are gone is removed. - Options: none.
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.