Command line, environment and --dart-define
Config files hold the values an application ships with. The sources on this page change them at launch or at build time, without editing a file. Each one wins over the config files; the full order is on the overview.
Why
A server in a container gets its settings as environment variables. A CI job passes options on the command line. A Flutter app has neither, so it gets per-build values as --dart-defines. All of them reach the same keys, under the names each source can write.
Example
# lib/resources/application.yml
shop:
max-basket-size: 10
api-url: http://localhost:8080
dart run bin/main.dart --shop.max-basket-size=30 # command line
SHOP_MAXBASKETSIZE=30 dart run bin/main.dart # environment variable
SPRING_APPLICATION_JSON='{"shop":{"max-basket-size":30}}' dart run bin/main.dart
flutter run --dart-define=SHOP_API_URL=https://api.neon.books # build time
All four set shop.max-basket-size (or shop.api-url), which @Value(r'${shop.max-basket-size}') and @ConfigurationProperties('shop') read.
Command line
dart run bin/main.dart --shop.max-basket-size=30 --spring.profiles.active=prod --debug
--key=valuesetskey; only the first=separates.--flagalone setsflagto an empty value (--debugturns on the condition report).- A repeated option keeps all its values, joined with commas.
- A lone
--ends the options; what follows are plain arguments. - Plain arguments are not properties. Runners get them through
ApplicationArguments.nonOptionArgs(see Runners).
A Flutter desktop app passes its arguments with SpringApplicationWidget(args: ...).
Environment variables
SHOP_MAXBASKETSIZE=20 sets shop.max-basket-size. The name is split at _ and lower-cased, and dashes do not matter. A part that is a number becomes an index:
| Variable | Key |
|---|---|
SHOP_MAXBASKETSIZE |
shop.max-basket-size (also shop.maxBasketSize) |
SHOP_HOSTS_0_ or SHOP_HOSTS_0 |
shop.hosts[0] |
APP_MAIN_SERVER_HOST |
app.main-server.host (bound to a nested object) |
SPRING_PROFILES_ACTIVE |
spring.profiles.active |
LOGGING_LEVEL_NEON_CHECKOUT |
logging.level.neon.checkout |
Phones and browsers have no useful environment. A Flutter app reads it only when the build defines spring.flutter.scan-os-environment=true.
Relaxed names
A property has a canonical name in kebab case: lower-case words joined by -, such as shop.max-basket-size. Each source may write it its own way, and it still matches:
| Written as | Where |
|---|---|
shop.max-basket-size |
the canonical form, recommended in files |
shop.maxBasketSize |
camel case, in files |
shop.max_basket_size |
underscores, in files |
SHOP_MAXBASKETSIZE, SHOP_MAX_BASKET_SIZE |
environment variables and --dart-define |
Inside [...], a map key is taken exactly as written. Code that reads a key (@Value, environment.getProperty) should use the canonical form.
--dart-define
Values given at build time with --dart-define (-DKEY=value for dart run and dart compile) are a property source right below the command line, above the environment and the config files. They take the relaxed names of environment variables:
flutter build apk --dart-define=SPRING_PROFILES_ACTIVE=prod \
--dart-define=API_URL=https://api.neon.books
flutter build apk --dart-define-from-file=config/prod.json
dart compile exe bin/main.dart -DSHOP_MAXBASKETSIZE=30
@Value(r'${API_URL}') String apiUrl // https://api.neon.books
@Value(r'${api.url}') String sameUrl // relaxed, like an environment variable
SPRING_PROFILES_ACTIVE activates application-prod.yml, so profiles can replace build flavors.
On the web and in AOT builds, String.fromEnvironment works only as a const with a literal key, so a define must be known when the program is compiled. The generator therefore lists every key the application can read, each also in its environment form, as SpringApplication(dartDefines: ...):
- the
${...}placeholders of annotations; - the
@ConditionalOnPropertynames; - the fields of
@ConfigurationPropertiesclasses; - the keys and placeholders of the
application*config files; spring.profiles.active.
A key read only in code (environment.getProperty('x')) is not listed: put it in application.properties (even empty), or pass it to SpringApplication(dartDefines: {...}) yourself. See --dart-define keys.
Defines are compiled into the program and can be read from an APK, an IPA or main.dart.js. Never pass passwords or private keys this way.
SPRING_APPLICATION_JSON
A JSON object in the environment variable SPRING_APPLICATION_JSON, or in the property spring.application.json (for example on the command line). It is flattened into properties right above the environment variables, below the command line and the --dart-defines. Handy where a platform passes configuration as one variable:
SPRING_APPLICATION_JSON='{"shop":{"hosts":["a","b"],"max-basket-size":30}}' dart run bin/main.dart
# shop.hosts[0]=a, shop.hosts[1]=b, shop.max-basket-size=30
dart run bin/main.dart --spring.application.json='{"server":{"port":9090}}'
The JSON comes from the first source that has either name. It is read before the config files, so it can set spring.config.* and spring.profiles.active. JSON that cannot be parsed, or that is not an object, fails the start.
In code
| Where | Precedence | Use |
|---|---|---|
SpringApplication(defaultProperties: {...}), or setDefaultProperties |
Lowest: every file overrides it | Defaults of a program that may run without a config file |
run(args, properties: {...}) |
Highest: above the command line | Tools and tests (springBootTest(properties:) is built on it) |
run(args, systemEnvironment: {...}) |
Replaces the OS environment | Tests |
SpringApplication(environmentPostProcessors: [...]) |
Any: the code adds sources where it wants | Settings from a server or a vault, computed profiles |
// A tool that works without application.properties.
void main(List<String> args) => SpringApplication(
[toolBeans],
defaultProperties: {'tool.output': 'out/', 'logging.level.root': 'warn'},
).run(args);
EnvironmentPostProcessor is described on Imports.
Placeholders
A value can contain other properties: ${key} is replaced by the value of key, and ${key:default} uses default when key is not set.
shop:
name: NEON Books
title: ${shop.name} (${spring.profiles.active:local})
url: ${SHOP_URL:http://localhost:8080}
api: ${shop.url}/api/v${shop.api-version:1}
literal: \${not.a.placeholder}
\${gives a literal${. In.propertieswrite\\${.${db:url}is first looked up as the keydb:url, then asdbwith the defaulturl, as in Spring 6.2.- A placeholder that cannot be resolved and has no default fails where the value is needed (
@Value,getProperty), with a report naming it.@ConfigurationPropertiesbinding keeps it as written. - In Dart, write
@Valuestrings as raw strings (r'${shop.name}'), because'${...}'is Dart's string interpolation. #{...}(SpEL) is evaluated only in@Valueand@ConditionalOnExpression, never in config files.
See Placeholders.
Random values
${random.*} gives a new random value on every read, for values that must differ per run:
| Placeholder | Value |
|---|---|
${random.int}, ${random.long} |
Any int or long (at most 53 bits on the web) |
${random.int(10)}, ${random.int[5,10]}, ${random.long(100)} |
A number in a range; the upper bound is excluded |
${random.uuid} |
A random version 4 UUID |
${random.value}, or any other random.* |
32 random hex digits |
Writing values
Every value is text; it is converted when it is bound to a typed field.
| Type | Forms |
|---|---|
Duration |
10s, 500ms, 5m, 1h, 2d (units ns, us, ms, s, m, h, d, any case); ISO-8601 PT10S, P1DT2H (no years or months); a plain number is milliseconds, or the unit of @DurationUnit |
DataSize |
512B, 10KB, 5MB, 1GB, 1TB, any case, powers of 1024, whole numbers only; a plain number is bytes, or the unit of @DataSizeUnit |
bool |
true, on, yes, 1 / false, off, no, 0, any case; anything else fails the start |
| enums | Matched ignoring case and separators: ONLY_SHOW_SELECTED, only-show-selected, onlyShowSelected |
| numbers | Decimal, or hex (0x1F, #1F); an empty value counts as "not set" |
| lists | A comma list, a YAML list or indexed keys |
See Durations and Data sizes.
Renamed properties
A few of Spring Boot's prefixes carry Java history that means nothing in Dart. They have other names here:
| Spring Boot | Here |
|---|---|
spring.jackson.* |
spring.json.* |
spring.cloud.openfeign.* |
spring.feign.* |
spring.servlet.multipart.* |
spring.web.multipart.* |
server.servlet.* |
server.* |
logging.logback.rollingpolicy.* |
logging.file.rolling-policy.* |
spring.flyway.* |
spring.sql.migration.* |
An old name is never ignored in silence. Any key under an old prefix, in any source (a file, the command line, a --dart-define, an environment variable such as SPRING_JACKSON_TIME_ZONE), stops the start:
Description:
These properties have been renamed:
- spring.jackson.default-property-inclusion is now
spring.json.default-property-inclusion
Spring Boot's spring-boot-properties-migrator only warns and keeps reading the old name; a forgotten server.servlet.session.* would then leave the sessions on their defaults.
In Spring (Java)
The command line, environment variables, relaxed binding, SPRING_APPLICATION_JSON, placeholders and random values follow Spring Boot. --dart-define has no Java counterpart (the nearest is -Dkey=value system properties). There is no .env file support.