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

## Why

The same build runs on a laptop, in tests and in production. Each place needs its own values, and nothing should be recompiled for that. So the settings live outside the code: in config files, on the command line, in environment variables and in `--dart-define` values.

The keys, file names and rules are Spring Boot's. Configuration from a Spring project usually works unchanged.

The annotations and the `Environment` are part of `spring_core_dart`. Reading the config files at startup and binding `@ConfigurationProperties` classes is done by `SpringApplication` (`spring_boot_dart` and the starters built on it). A plain `ApplicationContext.run` reads only the environment variables, unless you load the files yourself with `ConfigDataEnvironment`.

## How it fits together

- **Config files.** `application.properties`, `application.yml` or `application.yaml` in `lib/resources/`. The generator embeds them in the generated code, so they work on the Dart VM, in AOT builds, in Flutter and on the web. The two formats mean the same thing and can be mixed.
- **Profiles.** A profile names a situation, such as `dev` or `prod`. For each active profile, `application-<profile>.*` is read as well and wins over the plain file. `@Profile` registers beans only for some profiles. See [Profiles](profiles.md).
- **Property sources.** The command line, `--dart-define` values, environment variables and the config files are each a property source. For each key, the highest source wins. See [Property sources](property-source.md).
- **The Environment.** One object holds the ordered sources and the active profiles. Code reads a key from it when the key is only known at run time. See [Environment](environment.md).
- **Placeholders.** `${key}` and `${key:default}` refer to other properties, in config files, in `@Value` and in some annotations. See [Placeholders](placeholders.md).
- **Reading values in beans.** `@Value` injects one value. A `@ConfigurationProperties` class binds a whole prefix to typed fields.

## Example

```yaml
# lib/resources/application.yml
shop:
  title: NEON Books
  url: ${SHOP_URL:http://localhost:8080}
  max-basket-size: 20
  checkout-timeout: 30s
---
spring:
  config:
    activate:
      on-profile: prod
shop:
  url: https://neon.books
```

```dart
import 'package:spring_core_dart/spring_core_dart.dart';

// A whole prefix as a typed bean.
@ConfigurationProperties('shop')
class ShopProperties {
  String title = 'Shop';
  String url = '';
  int maxBasketSize = 10;
  Duration checkoutTimeout = const Duration(minutes: 1);
}

@Service()
class Checkout {
  Checkout(
    this.shop,
    // One value; a raw string, so Dart does not read `$`.
    @Value(r'${shop.title}') this.title,
  );

  final ShopProperties shop;
  final String title;
}
```

```bash
dart run bin/main.dart --spring.profiles.active=prod --shop.max-basket-size=30
```

## Pages of this section

- [@Value](value.md): inject one setting or a SpEL result into a bean.
- [@ConfigurationProperties](configuration-properties.md): bind a prefix to a typed class, with nested objects, lists, maps and validation.
- [Environment](environment.md): read properties and profiles in code.
- [Placeholders](placeholders.md): `${key}`, `${key:default}`, nesting and escapes.
- [Profiles](profiles.md): activate profiles, profile files, `@Profile`, profile expressions.
- [Property sources](property-source.md): where values come from, which source wins, adding your own.

## In Spring (Java)

This is Spring Boot's *Externalized Configuration*. Differences that matter:

- `lib/resources/` plays the role of the classpath. Its location prefix is `resources:`, not `classpath:`.
- There are no JVM system properties. `--dart-define` values are a source just below the command line.
- `.properties` files are read as UTF-8, not ISO-8859-1.

The full reference, with every key the framework reads, is [configuration.md](https://github.com/farum-azula/spring_core_dart/blob/main/docs/configuration.md) on GitHub.

## See also

- [Beans](../beans/index.md)
- [ConversionService](../conversion/conversion-service.md)
- [Durations](../conversion/durations.md)
- [Validation](../validation/index.md)