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

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: ...):

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}

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.

See also