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:

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:

  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:

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

See Pages for search engines.

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.