
# 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.dart` file 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, because `build_runner` would 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`](#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`](#spring_properties) | every `.dart` file of `lib/` | `lib/spring_gen/<path>.spring.dart` | a package enables it (off by default) |
| [`spring_test`](#spring_test) | `test/**_test.dart` | `test/spring_gen/<name>.test.spring.dart` | the file has `@SpringBootTest` or `@DataTest` classes |
| [`spring_prefetch`](#spring_prefetch) | the package | `lib/resources/spring_gen/prefetch/resources.json` | `spring.resources.prefetch.locations` is set |
| [`spring_search_index`](#spring_search_index) | the package | `lib/resources/spring_gen/search/<language>.json` | `spring.search.markdown` is set |
| [`spring_json_schemas`](#spring_json_schemas) | the package | `lib/spring_gen/json_schemas.spring.classes.dart` | `spring.json.schemas` is set |
| [`spring_metadata`](#spring_metadata) | the package | `lib/spring_gen/spring_metadata.json` | `lib/` or `bin/` has Spring code |
| [`spring_flutter_keys`](#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`](#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`](#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`](#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`](#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 `.dart` file of `lib/`, `bin/`, `test/` or `example/`. If its text contains `ComponentScan` or `SpringBootApplication`, the file is resolved, then every library under its scan root, the files of `lib/resources/`, `pubspec.yaml`, and (for an application) the `lib/spring_auto_configuration.dart` of every dependency.
- **Writes:** `<root>/spring_gen/<path>.spring.dart`: a `BeanModule` for a [`@ComponentScan` variable](component-scan.md), or the whole [application](spring-boot-application.md) for a `@SpringBootApplication` `main`.
- **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](optimizations/aop-proxies.md) |
| `aop_prune` | `true`, `false` | `true` | [AOP proxies](optimizations/aop-proxies.md) |
| `aop_defer` | `true`, `false` | `false` | [AOP proxies](optimizations/aop-proxies.md) |
| `dart_defines_exclude` | a list of property name prefixes | `[]` | [--dart-define keys](dart-defines.md#leaving-keys-out) |

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](options.md).

```yaml
# 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 `@ConfigurationProperties` classes through a `@ComponentScan` library in `lib/`, and its own `lib/` imports the generated module. Its example (generated by the main builder) imports that `lib/`. A builder cannot read what another input of its own phase writes, so the `lib/` 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 with `enabled: true`, and limits the main builder to its example:

```yaml
# 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](tests.md).

- **Reads:** each `test/<name>_test.dart`. If its text contains `SpringBootTest` or `DataTest`, it is parsed (not resolved) and its test classes are read. It also looks at the `.dart` files of `bin/` and `lib/` to find the application under test.
- **Writes:** `test/spring_gen/<name>.test.spring.dart` with a `runSpringTests()` function, which the test's `main` calls.
- **Silent:** for test files without `@SpringBootTest` or `@DataTest` classes.
- **Options:** none.

## spring_json_schemas

Writes the classes of the JSON Schemas of `spring.json.schemas`. See [JSON Schema classes](json-schema-classes.md).

- **Reads:** `spring.json.schemas[n].*` (as the app reads it, without a profile), the schemas of `resources:` in `lib/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.dart` library. The main builder gives the module the introspections of its classes and embeds a remote schema as a resource.
- **Silent:** when `spring.json.schemas` is 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](resources.md#downloading-them-together).

- **Reads:** `spring.resources.prefetch.locations` (without a profile) and the text files of `lib/resources/` its globs match.
- **Writes:** `lib/resources/spring_gen/prefetch/resources.json`, a line per piece, on disk (no declared outputs). Never embedded; a missing `flutter: 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](../spring-search-dart/searching.md#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 those `resources:` locations, cut and analyzed by the app's own `spring_search_dart`: the builder runs its `bin/search_index.dart` with 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 under `flutter: assets:`, warned about when missing.
- **Silent:** without `spring.search.markdown`, with `spring.search.prebuilt: false` or `spring.search.enabled: false`, or for a location outside `resources:`. 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](metadata.md).

- **Reads:** the `.dart` files of `lib/` and `bin/` (generated files left out), and `lib/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/` or `bin/` mentions Spring code: `ComponentScan`, `SpringBootApplication`, `AutoConfigurationModule`, `ConfigurationProperties`, a hand-written `BeanDefinition<`, `@Component`, `@Service`, `@Configuration`, `@Bean`, `@ThemeLoaderKind`, `@ScreenRoute` or `@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](flutter/typed-keys.md).

- **Reads:** every `.yml`, `.yaml` and `.properties` file of `lib/resources/` (any profile, any theme), the `resources:` files that `spring.config.import` names from a dependency, the `@ThemeLoaderKind` classes of `lib/`, and the loader kinds listed in the `spring_metadata.json` of the dependencies.
- **Writes:** `lib/spring_gen/theme.spring.keys.dart` (with `spring.flutter.theme.*` properties) and `lib/spring_gen/messages.spring.keys.dart` (with `messages*.properties` files). Both are `part of` the `.spring.dart` of the package's `@SpringBootApplication` library, else of its outermost `@ComponentScan`.
- **Silent:** when no dependency name in `pubspec.yaml` starts with `spring_boot_starter_flutter`, or when there are neither theme properties nor message files. If no library has a `@ComponentScan` or `@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](flutter/web-dev-server.md).

- **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.yaml` in 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 or `spring.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](flutter/page-loader.md).

- **Reads:** `lib/resources/` (the theme), `web/index.html`, and the `web:` HTML files of the app's own loader kinds.
- **Writes:** a block between `<!-- spring:loader:start -->` and `<!-- spring:loader:end -->` in `web/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 when `web/index.html` does not exist (it is never created). Most of what it cannot use (a loader's `web:` file it cannot read, for example) is a warning, not an error.
- **Runs before** `spring_flutter_seo`, whose pages are copies of `web/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](flutter/seo.md).

- **Reads:** `spring.flutter.web.seo.*` (with the `web` profile), the Markdown files of `lib/resources/`, `web/index.html`, and the routes in `lib/spring_gen/spring_metadata.json`.
- **Writes:** into `web/`: `<path>/index.html` per page, `<path>.md`, `sitemap.xml`, `robots.txt`, `llms.txt` and `llms-full.txt`; the root page into `web/index.html` between `spring:seo` markers. The files it wrote are listed in `web/.spring-seo`, so a page that is gone is deleted on the next build.
- **Silent:** unless `spring.flutter.web.seo.enabled` is `true` and `web/index.html` exists (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](flutter/deep-links.md).

- **Reads:** `spring.flutter.navigation.deep-links.*`, read per platform with that platform's profiles (`ios` and `mobile`, `android` and `mobile`, `macos` and `desktop`).
- **Writes:** blocks between `spring:deep-links:start` and `spring:deep-links:end` in `ios/Runner/Info.plist`, `ios/Runner/Runner.entitlements` (when it exists), `macos/Runner/Info.plist` and `android/app/src/main/AndroidManifest.xml`; and `apple-app-site-association` and `assetlinks.json` (into `web/.well-known/` for an app with a web version, else `build/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`):

```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`:

```yaml
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

- [How the generation works](how-it-works.md)
- [Options](options.md)
- [Flutter](flutter/index.md)
