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 keepwatchrunning). A hot restart is not enough. - Only the files count. The build cannot see environment variables,
--dart-definevalues 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.ymlfor the web builders,application-ios.ymlfor 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:
# 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]
# 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:
application.properties,.ymland.yamlinlib/resources/andlib/resources/config/;- the files of the added profiles (
application-web.yml), which win over the files of step 1, as in the app; - the files of the profiles that
spring.profiles.active(and.include,.group.*) names in those files, and of thedefaultprofile when none is active (application-default.yml); - the files
spring.config.importnames withresources:(from the package's ownlib/resources/), and the documents whosespring.config.activate.on-profilematches.
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}isdev). Otherwise, a profile name with such a placeholder is left out,spring.profiles.validateandspring.main.cloud-platformcount as unset, an import location is not read, and a document whosespring.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,profileorreleasewhen it starts. No builder adds it, soapplication-release.ymlis not read at build time unlessspring.profiles.activenamesrelease. - The file system. A browser has none, and a phone's is not the build machine's. A
file:,configtree:orpackage:import is skipped,optional:or not. An import the build cannot read at all (http:,asset:, aresources:file missing fromlib/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.
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.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 |
These are the AutoConfigurationBuild properties of the family; the table of every module, with its platform, is on Modules of one platform. 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:
// 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:
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.
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.
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.
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 |
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.
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 |
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.
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.
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.