
# 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.

```yaml
# lib/resources/application.yml: shipped with the program
shop:
  url: http://localhost:8080
```

```yaml
# lib/resources/application-prod.yml: read with the prod profile
shop:
  url: https://neon.books
```

```bash
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
```

```dart
// 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](config-files.md) |
| Profile files and documents | `application-{profile}.*`, and documents with `spring.config.activate.on-profile` | [Profiles](profiles.md) |
| Imports | `spring.config.import`: more files, directories, config trees, HTTP, packages, assets | [Imports](imports.md) |
| Command line | `--key=value` | [Command line, environment and --dart-define](sources.md) |
| Environment variables | `SHOP_URL=...`, with relaxed names | [Command line, environment and --dart-define](sources.md) |
| `--dart-define` | Values compiled into the program | [Command line, environment and --dart-define](sources.md) |
| `SPRING_APPLICATION_JSON` | One JSON object in a variable or property | [Command line, environment and --dart-define](sources.md) |
| Code | `SpringApplication(defaultProperties:)`, `run(properties:)`, `EnvironmentPostProcessor` | [Command line, environment and --dart-define](sources.md) |
| `@PropertySource` | Files named on a configuration class | [Property sources](../../spring-core-dart/config/property-source.md) |

## 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](../configuration-properties.md).

## 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. `EnvironmentPostProcessor`s 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 `EnvironmentPostProcessor`s run, among them the check for [renamed properties](sources.md#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](../hot-reload.md) 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](../../spring-core-dart-generator/metadata.md).

## In Spring (Java)

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

- `lib/resources/` is the classpath, written `resources:` (not `classpath:`).
- `--dart-define` values are a source of their own, right below the command line. Java has no counterpart; the nearest is `-Dkey=value`.
- `.properties` files are UTF-8, not ISO-8859-1.
- No `env:` imports, no XML properties files, no Spring Cloud Config client. HTTP imports exist (`spring.config.import=https://...`), with an asynchronous start.

The full list is on [Differences from Spring](../differences.md).

## See also

- [Config files](config-files.md)
- [Profiles](profiles.md)
- [Imports](imports.md)
- [Command line, environment and --dart-define](sources.md)
- [@ConfigurationProperties](../configuration-properties.md)
- [Environment](../../spring-core-dart/config/environment.md)
- [Placeholders](../../spring-core-dart/config/placeholders.md)
