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= |
- A YAML list becomes indexed keys (
shop.hosts[0],shop.hosts[1]). The plain keyshop.hostsis not set, so@Value(r'${shop.hosts}')finds nothing. Write a comma list (hosts: eu,us) for code that reads one key. Spring Boot behaves the same way. - Indexes start at 0 and have no gaps.
- For a target that is not a
String, an empty value counts as "not set", so the default applies.
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
- Files are read as UTF-8, so
Grüßecan be written as is. Spring Boot reads ISO-8859-1. A file that is not valid UTF-8 fails the start with aConfigDataLoadExceptionnaming it. Name another encoding where the file is named:resources:legacy.properties[encoding=iso-8859-1](UTF-8, ISO-8859-1 and US-ASCII are known, with Java's names and aliases such aslatin1). - When a key appears twice, the last value counts. Trailing spaces of a value are kept.
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):
on,off,yesandnostay strings; they still convert toboolwhere aboolis expected, andoffworks for an enum with anoffconstant (spring.main.banner-mode: off);0777is the number 777, not octal;- a duplicate key or invalid YAML fails the start with its line and column.
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.
Changing the search
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
- A required file that does not exist fails the start:
Config data resource 'file [./override.yml]' via location 'file:./override.yml' does not exist, with the actionprefix it with 'optional:'. - A required directory that does not exist, or a wildcard with no match, fails too.
optional:makes one location optional;spring.config.on-not-found=ignoremakes all of them optional.- The profile variants searched by name (
application-dev.yml) are always optional. - A location counts as found when one of its profile variants is found, as in Spring Boot.
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:
resources:instead ofclasspath:, and noresources*:or wildcard search in config locations..propertiesfiles are UTF-8;PropertiesPropertySourceLoader(encoding: latin1)gives Spring Boot's ISO-8859-1.- YAML 1.2 instead of 1.1.
- No
application.xml:spring.config.import=x.xmlfails the start ("XML properties files are not supported"). - In a
;group, spaces around an entry are trimmed and empty entries skipped.