
# Properties the build reads

Most properties are read by the app when it starts. A few are read earlier, by the generator, while `build_runner` runs: they decide what code is generated, which modules are compiled in, and what goes into files outside `lib/` (`web/index.html`, `Info.plist`, `web_dev_config.yaml`). This page lists every one of them, grouped by builder, and says which configuration files each builder reads.

## Why

A property read at build time behaves differently from one read at run time:

- **Changing it needs a build.** Edit the file, then run `dart run build_runner build` (or keep `watch` running). A hot restart is not enough.
- **Only the files count.** The build cannot see environment variables, `--dart-define` values or command-line arguments: they exist only when the app runs. A placeholder that only they can fill is unknown at build time.
- **Profiles are read differently by each builder.** Some builders read the files as the app reads them on one platform (`application-web.yml` for the web builders, `application-ios.yml` for iOS). Some read every file whatever its profile. One reads the profile-less files only. Knowing which is which tells you where to put a key so the build sees it.

## Example

The configuration of a web app, with the builder that reads each build-time key in a comment:

```yaml
# lib/resources/application.yml
spring:
  messages:
    basename: messages,errors          # spring_flutter_keys: typed messages
  flutter:
    debug:
      enabled: false                   # spring_core_dart: no debug panel code at all
    app:
      title: NEON Books                # spring_flutter_page_loader: <title>, manifest.json
      description: Books, in neon.     # spring_flutter_page_loader: <meta name="description">
    theme:
      active: system                   # spring_flutter_keys and spring_flutter_page_loader
      splash:
        loader: ring                   # spring_flutter_page_loader: the page loader
    navigation:
      deep-links:
        scheme: neonbooks              # spring_flutter_deep_links
        domains: [books.example.com]
```

```yaml
# lib/resources/application-web.yml (the web profile: read by the web builders)
spring:
  flutter:
    web:
      dev-server:
        port: 5050                     # spring_flutter_web: web_dev_config.yaml
      page:
        max-pixel-ratio: 2             # spring_flutter_page_loader: a script in web/index.html
      seo:
        enabled: true                  # spring_flutter_seo: a page per route
        site-url: https://books.example.com
```

## How each builder reads the configuration

The generator reads the configuration in four ways. Each builder uses one of them; the tables below say which.

### 1. As the app reads it on one platform

The builder loads the files with the same configuration loader the app uses at start, with the profiles the app adds on that platform:

| Builder | Profiles added | Used for |
|---|---|---|
| `spring_flutter_web` | `web` | `spring.flutter.web.dev-server.*`, `spring.flutter.security.web.mode` |
| `spring_flutter_seo` | `web` | `spring.flutter.web.seo.*`, `spring.flutter.navigation.languages` |
| `spring_flutter_page_loader` | `web` | `spring.flutter.app.title`, `.description`, `spring.flutter.web.page.*`, `spring.web.resources.cache.cachecontrol.*` |
| `spring_flutter_deep_links` | `mobile` then `ios`, `mobile` then `android`, `desktop` then `macos` (once per platform; the platform's own file wins) | `spring.flutter.navigation.deep-links.*` |
| `spring_core_dart` | none | the property of each `AutoConfigurationBuild` |
| `spring_json_schemas` | none | `spring.json.schemas[n].*` |
| `spring_search_index` | none | `spring.search.markdown[n].*`, `spring.search.analyzers.*`, `spring.search.prebuilt` |

What the loader reads, in order:

1. `application.properties`, `.yml` and `.yaml` in `lib/resources/` and `lib/resources/config/`;
2. the files of the added profiles (`application-web.yml`), which win over the files of step 1, as in the app;
3. the files of the profiles that `spring.profiles.active` (and `.include`, `.group.*`) names in those files, and of the `default` profile when none is active (`application-default.yml`);
4. the files `spring.config.import` names with `resources:` (from the package's own `lib/resources/`), and the documents whose `spring.config.activate.on-profile` matches.

What it cannot know, and what it does instead:

- **Placeholders only the running app resolves** (`${ENV}` with no default, set by an environment variable or a `--dart-define`). A default is used when there is one (`${APP_PROFILE:dev}` is `dev`). Otherwise, a profile name with such a placeholder is left out, `spring.profiles.validate` and `spring.main.cloud-platform` count as unset, an import location is not read, and a document whose `spring.config.activate.*` has one is skipped. Each case is a warning that names it, never an error.
- **The build-mode profile.** The app adds `debug`, `profile` or `release` when it starts. No builder adds it, so `application-release.yml` is not read at build time unless `spring.profiles.active` names `release`.
- **The file system.** A browser has none, and a phone's is not the build machine's. A `file:`, `configtree:` or `package:` import is skipped, `optional:` or not. An import the build cannot read at all (`http:`, `asset:`, a `resources:` file missing from `lib/resources/`) is skipped silently: it may exist at run time.

These builders read only the package's own `lib/resources/`. Where a key may be is checked as the app checks it: `spring.profiles.active` inside a profile file (`application-web.yaml`) is an error, as it is at the app's start.

### 2. Every file, whatever its profile

The builder reads the keys of every `.properties`, `.yml` and `.yaml` file of `lib/resources/`, in path order, without applying profiles, plus the files that `spring.config.import` names with `resources:` and that a dependency ships (`resources:themes/neon.yml` from a theme package):

| Builder | Used for |
|---|---|
| `spring_flutter_keys` | `spring.flutter.theme.*` (the keys of every theme), `spring.messages.basename` |
| `spring_flutter_page_loader` | `spring.flutter.theme.*` (the splash, loaders and colours), `spring.remote.allow-insecure` |
| `spring_metadata` | `spring.flutter.theme.loaders.*` of every theme (the keys each loader kind takes) |

For typed keys this is what you want: a key declared only in `application-dark.yml` still gets an accessor. For values it means profile precedence does not apply: when two files set the same key, the file later in path order wins (`application.yml` comes after `application-web.yml`). The single-valued keys `spring.messages.basename` and `spring.remote.allow-insecure` take the first file in path order that sets them. Keep each of these keys in one file.

### 3. The profile-less files only, strictly

The checks of `@Query` texts against the schema read `application.properties`, `.yml` and `.yaml` of `lib/resources/` and `lib/resources/config/`, and nothing else. When something else might change the result (a profile file or a profile-only document that sets a `spring.sql.*` key, a `spring.config.import`, a location outside `lib/resources/` or with a placeholder, a named data source, a file that does not parse), the build does not report misspelled tables and columns, since it cannot be sure.

### 4. Key names only

For the `--dart-define` keys of the `@SpringBootApplication` output, the main builder collects the key names of the `application*` files of `lib/resources/` (all profiles). It does not read their values. See [--dart-define keys](dart-defines.md).

## The main builder: `spring_core_dart`

| Property | Read | What it changes |
|---|---|---|
| The `property` of each `AutoConfigurationBuild` | As the app reads it, no platform profile (way 1) | Whether the module goes into the application: `true` in every build, `false` in none (no code), not set: the module's `whenMissing` (`notInRelease` by default) |
| `spring.flutter.debug.enabled` | The same: it is the `AutoConfigurationBuild` property of `spring_boot_starter_flutter`'s debug module | `true`: the debug panel is in every build; `false`: no debug panel code at all; not set: in debug and profile builds, compiled away in a release build |
| `spring.flutter.debug.frame-meter.enabled`, `.motion.enabled`, `.timeline.enabled`, `.isolates.enabled` | The same, each for a debug module of `spring_boot_starter_flutter` of its own | As `spring.flutter.debug.enabled`, for the frame meter, the motion switch, the timeline and the task manager |
| `spring.flutter.debug.drag.enabled` | The same | `true`: the debug overlays can be dragged; `false` or not set: no code for it |
| `spring.web.debug.qps.enabled` | The same: the property of `spring_boot_starter_web`'s `qps` module and of the actuator's `qps` endpoint | `true`: the application counts its requests and has the `qps` endpoint; `false` or not set: none of that code → [Requests per second](../spring-boot-starter-web/server/qps.md) |
| `spring.main.startup-checks.enabled` | The same: the property of the modules that hold the starters' startup checks (the data starter's `transactionValidator` and `dataFailureAnalyzer`, the cache starter's `cacheOperationValidator`, the edge starter's warning list) | `true`: the checks are in every build; `false`: no code for them at all; not set: in debug and profile builds, compiled away in a release build, where a mistake they would have found fails at the first call instead of the start |
| `spring.data.jdbc.show-sql` | The same: the property of the data starter's statement logging module | `true`: `show-sql`, `format-sql` and `show-parameters` work in every build; `false`: no code for them; not set: in debug and profile builds only (a profile such as `application-dev.yml` can still turn them on there; one that sets `show-sql` where the file without a profile does not is warned about, a release build has no code for it). `slow-query-threshold` stays in every build |
| `spring.observations.annotations.enabled` | The same: the property of `spring_boot_dart`'s `@Observed` module | `true`: `@Observed` is put into effect; `false` or not set: no advisor, and no proxy for it |
| `spring.sql.migration.locations`, `spring.sql.init.schema-locations`, `spring.sql.init.platform` | Profile-less files only (way 3) | Which SQL files of `lib/resources/` describe the schema the `@Query` checks compare with |
| `spring.resources.embed.exclude` | Profile-less files of `lib/resources/` | Which files of `lib/resources/` stay out of the binary; the configuration is always embedded → [Embedded resources](resources.md#leaving-files-out-of-the-binary) |

These are the `AutoConfigurationBuild` properties of the family; the table of every module, with its platform, is on [Modules of one platform](optimizations/build-conditions.md#which-modules-are-marked). A module's platform (`AutoConfigurationModule(platform:)`) is not a property: the build reads nothing for it. A starter of your own can declare more build properties:

```dart
// lib/spring_auto_configuration.dart of a starter
@AutoConfigurationModule(
  build: AutoConfigurationBuild('neon.debug.enabled'),
)
final BeanModule neonDebugAutoConfiguration = BeanModule(...);
```

A value other than `true` or `false` (case and spaces ignored) is a warning, and the module is built as when the property is not set. When the property is not set but a profile file (`application-web.yml`) sets it, the build warns that it does not read that file:

```text
spring_boot_starter_flutter.springBootStarterFlutterDebugAutoConfiguration: spring.flutter.debug.enabled is set only in application-web.yml, which the build does not read: it decides by application.yml or application.properties without a profile. The module is built as when it is not set.
```

Put the property in `application.yml` or `application.properties`. The debug beans of `spring_boot_starter_flutter` also carry a run-time condition on the same property (`@ConditionalOnProperty`, matching when it is missing), so `spring.flutter.debug.enabled: false` in a profile file still turns off, at run time, a panel the build put in. See [Modules left out of the build](optimizations/build-conditions.md).

For an application whose `main` is outside `lib/` (`example/`), the main builder also reads the `lib/resources/` of every directory down to `main`; the nearer one wins for a file of the same name.

## Typed keys: `spring_flutter_keys`

Runs for a package that depends on `spring_boot_starter_flutter` (or a starter that brings it). Reads every file (way 2).

| Property | What it changes |
|---|---|
| `spring.flutter.theme.*` and `spring.flutter.theme.themes.<name>.*` | The accessors of `context.theme` and the names of `AppThemes`. Only the keys and their kinds count; the values are read at run time from the active theme. |
| `spring.messages.basename` | The message files of `context.messages`: `<basename>.properties` and `<basename>_<locale>.properties` for each comma-separated base (`messages` by default). A placeholder in it is a warning, and no typed messages are written. |
| `spring.config.import` | Its `resources:` entries bring the files of a dependency's `lib/resources/` into the keys. |

See [Typed keys](flutter/typed-keys.md).

## The web dev server: `spring_flutter_web`

Runs for every package. It loads the configuration (way 1, profile `web`) only when a config file sets a `spring.flutter.web.dev-server.*` key or `spring.flutter.security.web.mode`; otherwise it does nothing and says nothing. Values must resolve at build time: a placeholder only the running app can fill is an error.

| Property | What it changes in `web_dev_config.yaml` |
|---|---|
| `spring.flutter.web.dev-server.host` | `server.host`: the address to listen on (`localhost`, `0.0.0.0`) |
| `spring.flutter.web.dev-server.port` | `server.port`: 0 to 65535, 0 picks a free port; a port browsers refuse is a warning |
| `spring.flutter.web.dev-server.base-href` | `server.base-href`: must start and end with `/` |
| `spring.flutter.web.dev-server.https.cert-path`, `.https.cert-key-path` | `server.https`: both or neither |
| `spring.flutter.web.dev-server.headers.<Name>` | `server.headers`: a header on every answer |
| `spring.flutter.web.dev-server.content-security-policy` | A `Content-Security-Policy` header |
| `spring.flutter.web.dev-server.content-security-policy-report-only` | `true`: the policy goes into `Content-Security-Policy-Report-Only` instead |
| `spring.flutter.web.dev-server.content-security-policy-connect-src` | Origins added to the ready policy of spa mode |
| `spring.flutter.web.dev-server.proxy[n].target`, `.prefix`, `.regex`, `.replace` | `server.proxy`: requests forwarded to other servers |
| `spring.flutter.security.web.mode` | `spa`: a ready Content Security Policy when the app sets none |
| `spring.security.oauth2.client.provider.*`, `.registration.*` | In spa mode: the origins the login fetches from go into the policy's `connect-src` |

An unknown key under `spring.flutter.web.dev-server` is a warning. A key directly under `spring.flutter.web` other than `dev-server`, `seo` and `page` (an old `spring.flutter.web.port`) fails the build and names the new key. See [The web dev server](flutter/web-dev-server.md).

## The page loader and the page head: `spring_flutter_page_loader`

Runs for a package that depends on `spring_boot_starter_flutter` and has a `web/index.html`.

| Property | Read | What it changes |
|---|---|---|
| `spring.flutter.theme.active`, `.system-light`, `.system-dark` | Every file (way 2) | Which theme's splash the page loader shows; for `system` (or not set), the light one and, under `prefers-color-scheme: dark`, the dark one |
| `spring.flutter.theme.splash.*` and `spring.flutter.theme.loaders.*` (also under `themes.<name>.`) | Every file | The page loader block between `<!-- spring:loader:start -->` and `<!-- spring:loader:end -->`: background, logo, title, the loader and its CSS variables. No splash: the block is removed |
| `spring.flutter.theme.loaders.<name>.web`, `.web-sha256` | Every file | The HTML file of a loader kind of your own, local or downloaded, and the hash that pins a downloaded one |
| The theme's colours (`colors.*`, the seed, references) | Every file | The colours of the block; `primary` gives `<meta name="theme-color">` and `theme_color`, `surface` the page background block and `background_color` |
| `spring.remote.allow-insecure` | Every file, first one | `true` allows a loader's `web:` address over plain `http` |
| `spring.flutter.app.title` | As the app reads it, profile `web` (way 1) | `<title>` and `apple-mobile-web-app-title` of `web/index.html`; `name` and `short_name` of `web/manifest.json` |
| `spring.flutter.app.description` | Profile `web` | `<meta name="description">` and `description` of `web/manifest.json` |
| `spring.flutter.web.page.max-pixel-ratio` | Profile `web` | A number of 1 or more: a script that caps the pixel ratio Flutter draws at. Otherwise no script |
| `spring.flutter.web.page.translate` | Profile `web` | `false`: `translate="no"` on `<html>` and `<meta name="google" content="notranslate">`, so browsers offer no translation of a page drawn on a canvas. Otherwise neither |
| `spring.flutter.web.page.swipe-to-close` | Profile `web` | `false`: a block that keeps the page open on a swipe down. Anything else: no block |
| `spring.web.resources.cache.cachecontrol.*` | Profile `web` | The block between `# spring:cache:start` and `# spring:cache:end` of `web/_headers` (created when missing): `no-cache` on every path, the `Cache-Control` the keys build on `/assets/*`, `no-cache` again on the assets that change with every build. No key set: the block is removed. A value it cannot read fails the build. See [The browser cache of a web build](../spring-boot-starter-flutter/cache-headers.md) |

When the configuration cannot be loaded for the `web` profile, the title, description and `page.*` keys count as unset and `web/_headers` is left as it is; the other builders report why. See [The page loader](flutter/page-loader.md).

## Pages for search engines: `spring_flutter_seo`

Runs for every package. It loads the configuration (way 1, profile `web`) only when a config file contains the text `seo`.

| Property | What it changes |
|---|---|
| `spring.flutter.web.seo.enabled` | `true` writes the pages; anything else writes none and deletes those written before |
| `spring.flutter.web.seo.site-url` | The site's address, for `canonical`, `og:url` and the sitemap; required when enabled |
| `spring.flutter.web.seo.from-routes` | `true`: the navigation's routes make pages |
| `spring.flutter.web.seo.title` | The `<title>` pattern, `{title}` for the page's (default `{title}`) |
| `spring.flutter.web.seo.description`, `.image`, `.site-name` | Defaults for pages without their own; `og:site_name` |
| `spring.flutter.web.seo.content[n].location`, `.path`, `.exclude` | Markdown folders (`resources:` or `asset:`) that make pages |
| `spring.flutter.web.seo.exclude` | files of every Markdown folder that make no page (`**/contents*.md`) |
| `spring.flutter.web.seo.pages[n].path`, `.title`, `.description`, `.image`, `.index` | Pages by hand, and overrides of what a route says |
| `spring.flutter.web.seo.sitemap` | `false`: no `sitemap.xml` and `robots.txt` (default `true`) |
| `spring.flutter.web.seo.llms` | `false`: no `llms.txt` and `llms-full.txt` (default `true`) |
| `spring.flutter.web.seo.markdown` | `false`: no `.md` copies (default `true`) |
| `spring.flutter.web.seo.page-files` | `directory` (`<path>/index.html`, the default) or `html` (`<path>.html`) |
| `spring.flutter.navigation.languages` | The pages are written in each language; the first has no prefix |

See [Pages for search engines](flutter/seo.md).

## Deep links: `spring_flutter_deep_links`

Runs for every package. It loads the configuration (way 1, once per platform) only when a config file contains `deep-links` or `deepLinks`.

| Property | What it changes |
|---|---|
| `spring.flutter.navigation.deep-links.enabled` | `false` removes the blocks of the platform whose profiles set it |
| `spring.flutter.navigation.deep-links.scheme` | `CFBundleURLTypes` (iOS, macOS), an intent filter (Android) |
| `spring.flutter.navigation.deep-links.domains` | `applinks:` in `Runner.entitlements`, a verified intent filter, the domain files |
| `spring.flutter.navigation.deep-links.exclude` | Excluded components in `apple-app-site-association` |
| `spring.flutter.navigation.deep-links.app-id` | The app id of `apple-app-site-association` |
| `spring.flutter.navigation.deep-links.package` | The package of `assetlinks.json` |
| `spring.flutter.navigation.deep-links.sha256-cert-fingerprints` | The fingerprints of `assetlinks.json`; without them the file is not written |
| `redirect-uri` (of an OAuth2 registration, `spring.security.oauth2.client.registration.<id>.redirect-uri`) | Searched in the text of every file: a redirect on the deep links' scheme is a warning |

See [Deep links](flutter/deep-links.md).

## JSON Schema classes: `spring_json_schemas`

Runs for a package whose configuration mentions `schemas`. Reads the configuration as in way 1, without a profile.

| Property | What it changes |
|---|---|
| `spring.json.schemas[n].location` | The schema to read or download: `resources:`, `https://`, `http://` or `github:` |
| `spring.json.schemas[n].sha256` | The digest a download must have; another is refused |
| `spring.json.schemas[n].prefix` | The start of the names of the classes of the schema |
| `spring.json.schemas[n].name` | The name of the root class |

See [JSON Schema classes](json-schema-classes.md).

## Where to put a build-time key

| The key is read by | Put it in |
|---|---|
| `spring_core_dart` (`AutoConfigurationBuild`) | `application.yml` or `application.properties` |
| The web builders (dev server, SEO, page head) | `application.yml` or `application-web.yml` |
| The deep links | `application.yml`, or the platform's file (`application-ios.yml`, `application-android.yml`, `application-macos.yml`) for one platform |
| `spring_json_schemas` (`spring.json.schemas`) | `application.yml` or `application.properties` |
| The typed keys and the page loader's theme | Any file; keep each key in one file |

And in every case: a literal value, or a placeholder with a default. A value from the environment or a `--dart-define` reaches the app, never the build.
