
# Build speed

The generator runs on every `.dart` file of `lib/`, `bin/`, `test/` and `example/`, under `build_runner build` and on every save under `build_runner watch`. Resolving Dart code with the analyzer is the expensive part of a build, so the generator is written to resolve as little as it can, and to do extra work only when there is something to gain from it.

This page lists what it does, as the code does it.

## Why

`build_runner watch` is part of the edit loop: a slow builder makes every save slow. The generator must look at the whole package for an application, and at the dependencies for auto-configurations and proxies, so it is easy to make it slow. Each item below avoids work the result does not need.

## Most files produce nothing, cheaply

The main builder declares one possible output per library (`lib/a.dart` may produce `lib/spring_gen/a.spring.dart`). For each input it first reads the text of the file and checks two words:

- An input whose text contains neither `ComponentScan` nor `SpringBootApplication` is skipped **without being resolved**. That is almost every file of a package.
- Generated files (`.spring.dart`) are never inputs.

Only the files that may declare a `@ComponentScan` variable or a `@SpringBootApplication` `main` are resolved.

## Nested scans are found by text first

A `@ComponentScan` or `@SpringBootApplication` build looks at every file below its directories to find nested `@ComponentScan` roots. A file whose text does not contain `ComponentScan` is not resolved for that search.

## Only the declarations that matter are resolved

Every scanned library is resolved to its elements (classes, members, annotations). Resolving the **bodies** of code is more expensive, and the generator does it only where a body tells something:

| What | Which bodies are resolved |
|---|---|
| The type a `@Bean` method really returns (`DataSource dataSource() => HikariDataSource(url)` registers a `HikariDataSource`) | only the `@Bean` methods, of the library's classes and of the classes they `@Import` |
| The initial values of fields (`IntrospectedProperty.initialValue`) | only the fields of `@Introspected` and `@Table` classes, of the DTOs of data repositories, and of classes a `@ConfigurationProperties` `@Bean` method returns |
| The calls of the `ObjectMapper` (see [Only what runs](introspection.md)) | only a library (or part file) whose text names one of `readValue`, `treeToValue`, `convertValue`, `readList`, `readMap`, `writeValueAsString`, `valueToTree`; `sendJson` and `broadcast` only in a library that imports the WebSocket starter |

A library that names no mapper method is not resolved for mapper calls at all.

## Starters' libraries are read by text first

The application's build looks into dependencies for two things, and uses text checks before it resolves:

- **Advice of auto-configurations, for proxy pruning.** For each auto-configuration library and the libraries of the same package it imports, the build reads the text. `AspectMetadata` in it means aspects the build cannot read (pruning is then off and the search stops early). Only a library whose text mentions `Advisor` has its declarations resolved, to read the advisors' pointcuts.
- **Deferred proxies.** Among the generated modules the auto-configurations and the application reach, only a `.spring.dart` file whose text contains `AopProxyFactory.deferred` has its getters resolved.

Only packages the application really depends on are searched (see [Auto-configurations](../auto-configurations.md)); in a pub workspace the siblings are skipped.

## Build conditions cost nothing until used

For [modules left out of the build](build-conditions.md):

- The configuration files are parsed into an environment only when the first module with `build:` is decided, then reused for the other modules of the build. An application whose starters use no `build:` never parses them for this.
- The profile files are searched only when the property is not set.
- The module declarations are walked for deferred proxies only when a module was decided `never` or `notInRelease`; the modules that are always in are walked only when those removed modules define such a bean. Each declaration is walked once.

## The test builder reads tests as syntax

The `spring_test` builder skips a test file whose text contains neither `SpringBootTest` nor `DataTest`. It reads the others as syntax (`parseString`), without the analyzer's resolution. It resolves a test file only when its syntax does not tell enough: a `@TestBean` field whose value is a constructor call (to know the class) or whose type may be a nullable type alias.

## Other builders do nothing without their properties

The Flutter builders run for every package that depends on the generator, pure Dart servers included. The `web_dev_config.yaml` builder, for example, does not even load the configuration unless a config file sets a `spring.flutter.web.dev-server.*` key or `spring.flutter.security.web.mode`. See [The builders](../builders.md).

## Stable output

The generated code is the same from one build to the next when the sources are the same:

- files, libraries and auto-configuration modules are processed in a fixed order (by path, by package and name);
- the `fingerprint` of the application (in its debug part, `main.spring.debug.dart`) is an FNV-1a hash of the generated code, stable across runs and platforms;
- the `build-info.properties` written for an application with the actuator has no build time.

## Fewer build runs for errors

- **All problems at once.** The scanner keeps going after a bad declaration and reports every independent problem of the build together (`N problems in this build:`), so you fix them in one round instead of one build per error. See [Build-time checks](../checks.md).
- **No flicker while you type.** While a scanned library has syntax errors, the existing generated file is written again unchanged, so the files that import it do not turn red and `watch` does not regenerate on every keystroke. See [Errors and the generated files](../errors.md).
- **The last good output is kept in memory.** Under `watch`, the builder keeps the last content it generated for each output and uses it when the sources break, without reading the disk.

## See also

- [Optimizations overview](index.md)
- [How the generation works](../how-it-works.md)
- [The builders](../builders.md)
- [Errors and the generated files](../errors.md)
