Config files

An application keeps its settings in application.yml, application.yaml or application.properties in lib/resources/. That folder is what Spring calls the classpath, and the resources: prefix points into it. For each active profile, application-{profile}.* is read as well, and its values win over the plain file.

You declare nothing in pubspec.yaml. The generator embeds every file of lib/resources/ into the generated code, so the files work the same on the Dart VM, in AOT executables, in Flutter and on the web. A file larger than 1 MB is not embedded (the build warns): ship it as a Flutter asset or as a file next to the program.

Why

One file per application, plus one per profile, keeps the defaults in one place and the differences small. Files next to the program (./application.yml, ./config/) let an operator change a setting of a server or a desktop app without a new build, and they win over the packaged ones, as in Spring Boot.

Example

lib/
  main.dart
  resources/
    application.yml               # always read
    application-dev.yml           # read with the dev profile
    application-prod.properties   # read with prod (the formats can be mixed)
    config/
      application.yml             # also packaged, wins over resources:/

The two formats say the same thing:

# lib/resources/application.yml
spring:
  application:
    name: shop
shop:
  title: NEON Books
  url: http://localhost:8080
  max-basket-size: 20
# lib/resources/application.properties
spring.application.name=shop
shop.title=NEON Books
shop.url=http://localhost:8080
shop.max-basket-size=20

Use the one you prefer, or both. When one location has both, .properties wins over .yml, which wins over .yaml.

The shapes of values

Both formats end up as the same flat list of keys and values.

Shape YAML .properties
Nested keys shop: / payment: / provider: stripe shop.payment.provider=stripe
A list hosts: / - eu.neon.books / - us.neon.books, or hosts: [eu, us] shop.hosts[0]=eu.neon.books, or shop.hosts=eu,us, or shop.hosts[]=eu, us
A list of objects servers: / - name: eu / url: https://eu.neon.books shop.servers[0].name=eu
A map prices: / book: 12 / e-book: 8 shop.prices.book=12
A map key with dots "[X-Shop.Id]": neon (quoted) shop.headers[X-Shop.Id]=neon
An empty value banner:, motto: ~ or null shop.banner=

Several documents in one file

One file can hold several documents. YAML separates them with ---; .properties with a line #--- (or !---). A later document overrides an earlier one. A document can be limited to some profiles or to a cloud platform, so one file can carry the development values and the production overrides:

shop:
  url: http://localhost:8080
---
spring:
  config:
    activate:
      on-profile: prod
shop:
  url: https://neon.books
shop.url=http://localhost:8080
#---
spring.config.activate.on-profile=prod
shop.url=https://neon.books

A .properties separator is the whole line: #--- or !--- at the start of the line, exactly three hyphens, nothing after them but spaces or tabs. It does not count right after a comment with the same prefix (leave a blank line, or use !---), nor where the line before continues with \. Put comments below the on-profile line, not right after the separator; Spring Boot joins such a document to the previous one, this loader does not.

See Profiles for on-profile expressions and on-cloud-platform.

Only in .properties

# The separator between key and value is =, : or whitespace.
shop.name=NEON
shop.city: Berlin
shop.country Germany

# A line ending in \ continues; the next line's leading spaces are dropped.
shop.welcome=Welcome to NEON Books, \
             the shop of books.

# Escapes: \t \n \r \f \uXXXX. In a key, \= \: and "\ " keep those characters.
shop.key\=with\:colon=yes

# A comment starts with # or ! at the start of the line; a # later is part of the value.
shop.color=#673AB7

Only in YAML

# An anchor shares a block; the mapping's own keys win over the merged ones.
defaults: &defaults
  timeout: 5s
  retries: 3
shop:
  eu:
    <<: *defaults
    url: https://eu.neon.books
  us:
    <<: *defaults
    retries: 5
  color: '#673AB7'   # quoted: a # after a space starts a comment

YAML is read as YAML 1.2 (Spring Boot's SnakeYAML reads 1.1):

Where files are searched

The locations come in two groups. The second group overrides the first entirely:

Group Locations, lowest first What they are
1, packaged resources:/, resources:/config/ lib/resources/ and lib/resources/config/, embedded by the generator
2, next to the program file:./, file:./config/, file:./config/*/ The working directory, ./config/ and each subdirectory of it in alphabetical order

So ./application.properties next to a server binary wins over the packaged application-prod.properties. Within a group, later locations win, profile files win over plain ones, and the last active profile wins. Every default location is optional.

In tests (springBootTest), test/resources/ comes before lib/resources/, so test/resources/application-test.yml is found, and a file there replaces a packaged file with the same path.

These keys change which files are searched. They are read only from the sources that exist before the files are read: the command line, --dart-define, the environment, SPRING_APPLICATION_JSON and the default properties. A config file cannot set them.

Key Type Default Meaning
spring.config.name comma list application The base names of the files. application,shop reads application*.* and shop*.*; a later name wins
spring.config.location locations the two groups above Replaces the default locations. , separates groups; ; joins locations into one group
spring.config.additional-location locations none Groups searched after the locations, so they win over them
spring.config.on-not-found fail / ignore fail ignore makes every location optional. Any other value fails the start
# Only the packaged files and /etc/shop/, which wins.
dart run bin/main.dart --spring.config.location=optional:resources:/,file:/etc/shop/

# The usual locations, then one more file on top.
dart run bin/main.dart --spring.config.additional-location=file:./override.yml

# Read shop.yml instead of application.yml.
SPRING_CONFIG_NAME=shop dart run bin/main.dart

A location written here takes every form of Imports: optional:, directories ending in /, wildcards, extension hints (file:./conf[.yml]), encoding hints, configtree:.

Missing files

Without SpringApplication

ConfigDataEnvironment is the class that does this work. A program on spring_core_dart alone, or a tool, runs it itself:

// Reads lib/resources/application.yml, ./application.properties, profiles and imports.
Future<void> main(List<String> args) async {
  final environment = StandardEnvironment()
    ..propertySources.addFirst(SimpleCommandLinePropertySource(args));
  await ConfigDataEnvironment(environment).processAndApply();
  print(environment.getProperty('shop.url'));
}

Its constructor takes a resourceLoader (for assets or files held in memory), loaders (the formats: PropertiesPropertySourceLoader and YamlPropertySourceLoader by default; a PropertySourceLoader of your own adds a format), defaultLocations and additionalProfiles. processAndApplySync() is the synchronous form.

In Spring (Java)

The same file names, locations and rules as Spring Boot, except:

See also