External configuration

Configuration is the settings that change from one place to another while the code stays the same: a server URL, a port, a timeout, a feature switch, a log level. spring_boot_dart reads them from outside the code, so one build runs on a laptop, in tests and in production, each with its own values, and nothing is recompiled.

This is Spring Boot's Externalized Configuration. The file names, keys and rules are Spring Boot's, so configuration from a Spring project usually works unchanged.

Why

A setting written in code needs a new build to change. A setting read from configuration can be changed by whoever runs the program: an operator with a file next to the binary, a container with an environment variable, a CI job with a command-line option, a Flutter build with a --dart-define. Spring Boot's rules decide which of them wins, so you can ship sensible defaults in lib/resources/application.yml and override any key from outside.

Example

The same key from five places. The highest source wins.

# lib/resources/application.yml: shipped with the program
shop:
  url: http://localhost:8080
# lib/resources/application-prod.yml: read with the prod profile
shop:
  url: https://neon.books
dart run bin/main.dart                                   # http://localhost:8080
dart run bin/main.dart --spring.profiles.active=prod     # https://neon.books
SHOP_URL=https://staging.neon.books dart run bin/main.dart   # the environment wins over files
dart run bin/main.dart --shop.url=http://127.0.0.1:9000      # the command line wins over all
// Any bean reads it the same way, whatever the source.
@Service()
class Links {
  Links(@Value(r'${shop.url}') this.url);

  final String url;
}

The sources

Source Where it comes from Page
Config files application.properties, application.yml, application.yaml in lib/resources/, lib/resources/config/, ./, ./config/, ./config/*/ Config files
Profile files and documents application-{profile}.*, and documents with spring.config.activate.on-profile Profiles
Imports spring.config.import: more files, directories, config trees, HTTP, packages, assets Imports
Command line --key=value Command line, environment and --dart-define
Environment variables SHOP_URL=..., with relaxed names Command line, environment and --dart-define
--dart-define Values compiled into the program Command line, environment and --dart-define
SPRING_APPLICATION_JSON One JSON object in a variable or property Command line, environment and --dart-define
Code SpringApplication(defaultProperties:), run(properties:), EnvironmentPostProcessor Command line, environment and --dart-define
@PropertySource Files named on a configuration class Property sources

Which source wins

When several sources set the same key, the highest one wins. From the highest:

  1. run(properties: ...), and springBootTest(properties: ...) in tests (the test's dynamicProperties are higher still).
  2. Command-line arguments (--shop.url=...).
  3. --dart-define values.
  4. SPRING_APPLICATION_JSON (or --spring.application.json).
  5. OS environment variables. Flutter apps do not read them unless the build switches it on.
  6. ${random.*} values.
  7. Config files, in this order (higher first):
    • spring.config.import given on the command line or in the environment;
    • then spring.config.additional-location;
    • then the locations: file:./config/*/, file:./config/, file:./ above resources:/config/, resources:/;
    • within each group, profile files above plain files, the last active profile highest;
    • an imported file above the file that imports it, and its profile variants above those of the importing file;
    • in one location, .properties above .yml above .yaml;
    • in one file, a later document above an earlier one.
  8. @PropertySource files.
  9. SpringApplication(defaultProperties: ...).

A list always comes whole from the highest source that has it: --shop.hosts[0]=local replaces the file's three hosts, it does not change the first one. Map entries are merged across sources, the higher source winning per key. See @ConfigurationProperties.

When the configuration is read

The configuration is read once, at the start, before any bean is created:

  1. The command line, the --dart-define values, the environment, the code's properties and ${random.*} become property sources.
  2. EnvironmentPostProcessors ordered before EnvironmentPostProcessor.configDataOrder run (SPRING_APPLICATION_JSON is one of them).
  3. The config files are read: locations, profiles, imports, documents. This is ConfigDataEnvironment.
  4. The other EnvironmentPostProcessors run, among them the check for renamed properties.
  5. ApplicationEnvironmentPreparedEvent is published, the log levels are applied and the beans are created.

runApplication reads the files synchronously. Locations that can only be read asynchronously (HTTP, Flutter assets) need runApplicationAsync, which Flutter apps use anyway.

Changing a config file needs a restart. In development, a hot reload restarts the context with the new values.

Editor completion

The generator writes lib/spring_gen/spring_metadata.json for every package with Spring code: the keys of its @ConfigurationProperties classes with their /// comments, types, defaults and allowed values. dart run tool/spring_schema.dart <app> (in the framework repository) turns the metadata of an application and its dependencies into a JSON Schema for the YAML language server, so application*.yml gets completion and checks. See Metadata.

In Spring (Java)

Everything on these pages follows Spring Boot's Externalized Configuration, with these main differences:

The full list is on Differences from Spring.

See also