
# Configuration in a Flutter app

A Flutter app with this starter keeps its settings in configuration files, as a Spring Boot app does: `application.yml` or `application.properties` in `lib/resources/`. The app widget, the themes, the splash, the shortcuts, the languages and your own settings all live there. This page explains where the files go, which ones are read on which device and build, and which source wins.

## Why

Settings in Dart code need a new build and a developer for every change, and the same `if (Platform.isIOS)` is written in many places. In files:

- a designer changes the theme in one YAML file;
- a platform gets its own values by file name (`application-ios.yml`), not by code;
- a release build gets its own values (`application-release.yml`), such as quieter logs;
- a build for a customer or a stage changes values with `--dart-define`, without touching a file.

The rules are the ones of Spring Boot, so the [configuration pages](../spring-core-dart/config/index.md) of `spring_core_dart` apply here too. This page lists what is special in a Flutter app.

## The files

```text
lib/
  main.dart
  resources/
    application.yml               # always read
    application-web.yml           # read in a browser only
    application-ios.properties    # read on iPhones and iPads only
    application-desktop.yml       # read on macOS, Windows and Linux
    application-release.yml       # read in release builds only
    application-dev.yml           # read when the profile dev is active
    themes/
      ocean.yml                   # imported by application.yml
    messages.properties           # texts (English)
    messages_ja.properties        # texts (Japanese)
```

- **No `pubspec.yaml` entry.** The generator embeds every file of `lib/resources/` into the generated code (`lib/spring_gen/main.spring.dart`), so the files work the same on every platform, in debug and release builds, and on the web. A file larger than 1 MB is not embedded (the build warns): ship it as a Flutter asset instead.
- **YAML and `.properties` mean the same thing.** Use either, or both. When one place has both, `.properties` wins over `.yml`, which wins over `.yaml`.
- **`resources:` points into `lib/resources/`.** `resources:themes/ocean.yml` is `lib/resources/themes/ocean.yml`. It is what Spring calls the classpath.
- **A change is a hot reload.** Because the files are part of the generated code, `build_runner watch` rewrites that code when you save one, and the next hot reload restarts the context with the new values (see [Hot reload](hot-reload.md)).

The same settings in both formats:

```yaml
# lib/resources/application.yml
spring:
  application:
    name: neon-books
  flutter:
    app:
      type: material
      title: NEON Books
      locales: en, ja
    theme:
      seed-color: deepPurple
shop:
  api-url: https://api.neon.books
  page-size: 20
```

```properties
# lib/resources/application.properties
spring.application.name=neon-books
spring.flutter.app.type=material
spring.flutter.app.title=NEON Books
spring.flutter.app.locales=en,ja
spring.flutter.theme.seed-color=deepPurple
shop.api-url=https://api.neon.books
shop.page-size=20
```

`type: material` and `seed-color` need [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) in the dependencies. With it as the one design starter, `type: material` may be left out: the starter decides, as Spring Boot deduces the web application type from the class path (see [The type when not set](app-widget.md#the-type-when-not-set)). An app without a design library is of type `widgets` and sets its colors under `colors.*` (see [Design libraries](design-libraries.md)).

The `spring.*` keys configure the framework; [All properties](properties.md) lists those of this starter. The `shop.*` keys are your own, read with `@Value` or a `@ConfigurationProperties` class (see [Reading your own settings](#reading-your-own-settings)).

## Platform profiles

A profile is a name that switches configuration files and beans on. `SpringApplicationWidget` makes the platform an active profile, with no setup:

| Platform | Profiles |
|---|---|
| Android | `mobile`, `android` |
| iOS | `mobile`, `ios` |
| macOS | `desktop`, `macos` |
| Windows | `desktop`, `windows` |
| Linux | `desktop`, `linux` |
| a browser | `web` |
| Fuchsia | `fuchsia` |

The specific profile comes after the group, so it wins: `application-ios.yml` over `application-mobile.yml` over `application.yml`.

```text
lib/resources/application.yml           shop.images: large
lib/resources/application-mobile.yml    shop.images: small     # phones: small images
lib/resources/application-ios.yml       push.provider: apns    # iPhones: Apple's push service
```

Beans follow the same profiles:

```dart
// Each platform gets its own push service.
@Component()
@Profile(['android'])
class FcmPushService implements PushService { ... }

@Component()
@Profile(['ios'])
class ApnsPushService implements PushService { ... }

@Component()
@Profile(['desktop', 'web'])
class NoPushService implements PushService { ... }
```

The profiles follow Flutter's `defaultTargetPlatform`. In a widget test the platform is Android unless the test sets `debugDefaultTargetPlatformOverride`.

## Build-mode profiles

The build is a profile too, added after the platform's:

| Build | Profile |
|---|---|
| `flutter run` (debug) | `debug` |
| `flutter run --profile` | `profile` |
| `flutter run --release`, `flutter build ...` | `release` |

So `application-release.yml` configures what your users run, and wins over `application-web.yml`:

```yaml
# lib/resources/application-release.yml
logging:
  level:
    root: warn
spring:
  flutter:
    frame-meter:
      enabled: false
```

On a release build in a browser the active profiles are `web` and `release`, in that order.

## Profiles of your own

Your own profiles (`dev`, `staging`, `customer-a`) are chosen as in Spring Boot. A Flutter app has no command line, so the usual way is a define at build time:

```bash
flutter run --dart-define=SPRING_PROFILES_ACTIVE=dev
flutter build apk --dart-define=SPRING_PROFILES_ACTIVE=staging
```

`spring.profiles.active` can also be set in `application.yml`, and `spring.profiles.group.<name>` makes one profile turn on others. The platform and build profiles are added to yours; they are not replaced by them. See [Profiles](../spring-core-dart/config/profiles.md) for the rules (which file may set which key, profile expressions).

## Documents for some profiles

Instead of a separate file, a document inside one file can be limited to some profiles. It is handy for a few values per platform:

```yaml
# lib/resources/application.yml
shop:
  columns: 2
---
spring:
  config:
    activate:
      on-profile: desktop | web
shop:
  columns: 4
---
spring:
  config:
    activate:
      on-profile: ios & release
push:
  sandbox: false
```

In `.properties`, documents are separated by a line `#---`.

## Imports

`spring.config.import` reads more files from inside a configuration file. Use it to split a large configuration: one file per theme, per feature, per region.

```yaml
# lib/resources/application.yml
spring:
  config:
    import:
      - resources:themes/ocean.yml
      - resources:themes/neon.yml
      - optional:resources:local.yml   # may be missing
```

- An imported file wins over the file that imports it, and it gets its own profile variants: `themes/ocean-web.yml` is read in a browser.
- Relative locations are relative to the importing file.
- A file is read once, so cycles do no harm.
- `optional:` makes a location that may be missing.

The locations a Flutter app can import:

| Location | What it reads |
|---|---|
| `resources:themes/ocean.yml` | A file of `lib/resources/`, embedded in the app |
| `asset:config/app.yml` | A Flutter asset, from the app's asset bundle (declared under `flutter: assets:`) |
| `https://cfg.example.com/app.yml` | A file on the network, read while the app starts (see [Remote files](#remote-files)) |
| `file:./local.yml` | A file on disk, for desktop apps; a browser has none |

## Themes in their own files

A theme is configuration like any other, so it can live in a file of its own. The file sets keys under `spring.flutter.theme`:

```yaml
# lib/resources/themes/ocean.yml
spring:
  flutter:
    theme:
      themes:
        ocean:
          extends: light
          seed-color: teal
          scheme-variant: vibrant
          components:
            card: { elevation: level0 }
        ocean-night:
          extends: ocean
          brightness: dark
```

```yaml
# lib/resources/application.yml
spring:
  config:
    import: resources:themes/ocean.yml
  flutter:
    theme:
      active: system
      system-light: ocean
      system-dark: ocean-night
```

This theme is for a Material app: `seed-color` and `scheme-variant` need a design starter, and `components` is read by spring_boot_starter_flutter_material (see [Theme properties](themes/properties.md)).

A theme can also come from a library. The `lib/resources/` folders of the packages the app depends on are on the same classpath, so a package that ships `lib/resources/themes/neon.yml` is imported with `resources:themes/neon.yml`, exactly like a file of the app (the NEON theme of `neon_ui` is used that way). And a theme can be downloaded by itself, cached and refreshed, with `themes.<name>.source` (see [Theme properties](themes/properties.md)).

## Remote files

Flutter apps start asynchronously, so a configuration file can come from the network: an `https://` location in `spring.config.import`. The start waits for the file, behind the splash.

```yaml
# lib/resources/application.yml
spring:
  config:
    import: optional:https://config.neon.books/app/application.yml
```

Three kinds of remote content are supported, each with its own behaviour:

| What | How | When it is read |
|---|---|---|
| A configuration file | `spring.config.import: https://...` | At every start, before the beans are created |
| A theme | `spring.flutter.theme.themes.<name>.source` | Downloaded once and cached; read again in the background with `refresh` (see [Theme properties](themes/properties.md)) |
| Values shared by every theme | `spring.flutter.theme.source` | Like a theme |
| An image of the theme | `source: https://...` in an image | Cached in the app's files; never delays the start (see [Images](themes/images.md)) |
| Themes from your own server | `SpringThemes.loadYaml(yaml)` in code | Whenever your code calls it (see [Themes](themes/index.md)) |

Every address the themes download from must be `https://` (or `github:owner/repo/path@ref`). An `http://` address stops the start with "the connection is not secure", naming the property, unless `spring.remote.allow-insecure=true`.

## `--dart-define`

A Flutter app has no command line, and the OS environment is of no use on a phone. Values for one build come from `--dart-define` instead. They form a property source that wins over the configuration files:

```bash
flutter run --dart-define=SPRING_PROFILES_ACTIVE=dev --dart-define=SHOP_API_URL=http://localhost:8080
flutter build web --dart-define-from-file=config/prod.json
```

- A define is read like an environment variable in Spring Boot: `SHOP_API_URL` answers `shop.api-url` and `@Value(r'${SHOP_API_URL}')`. The plain name (`shop.api-url`) works too.
- A compiled app can only read the defines whose names the generator wrote into `main.spring.dart`, because `String.fromEnvironment` needs a constant name. It writes every name the app can read: the `${...}` placeholders of annotations, the fields of `@ConfigurationProperties` classes, the keys of the configuration files, and a few such as `spring.profiles.active`. A define of any other name is not seen. See [--dart-define keys](../spring-core-dart-generator/dart-defines.md).
- Everything defined at build time ends up in the app and can be read from it: no secrets there.

## The OS environment

`SpringApplicationWidget` does not read the environment variables. A desktop build can turn them on:

```bash
flutter run -d macos --dart-define=spring.flutter.scan-os-environment=true
```

The key decides whether the environment is read at all, so only `--dart-define` can set it; a configuration file cannot. A desktop app that starts with arguments passes them with `SpringApplicationWidget(args: ...)`; they are read as `--name=value` properties.

## Which source wins

From the highest:

1. `springBootTest(properties: ...)` in tests
2. `SpringApplicationWidget(args: ...)`
3. `--dart-define` values
4. OS environment variables (only with `spring.flutter.scan-os-environment=true`)
5. Configuration files: an imported file above the file that imports it; profile files above plain ones, the last profile highest (so the build's profile, then the platform's specific one, then its group); `.properties` above `.yml` above `.yaml`; a later document above an earlier one
6. `SpringApplication(defaultProperties: ...)`
7. The values the starter sets for SQLite (`spring.datasource.sqlite.*`), below everything (see [SQLite databases](sqlite.md))

## Reading your own settings

Your own keys are read as in any Spring app. A group of settings is a `@ConfigurationProperties` class, checked at the start:

```dart
// shop.api-url and shop.page-size, from any file or define.
@ConfigurationProperties('shop')
@Validated()
class ShopProperties {
  String apiUrl = 'https://api.neon.books';

  @Min(5)
  @Max(100)
  int pageSize = 20;
}

@Service()
class Catalog {
  Catalog(this.shop, @Value(r'${shop.currency:EUR}') this.currency);

  final ShopProperties shop;
  final String currency;
}
```

`SizeConstraint` is the `@Size` constraint under another name, because Flutter's `Size` is everywhere in widget code. See [@ConfigurationProperties](../spring-core-dart/config/configuration-properties.md) and [@Value](../spring-core-dart/config/value.md).

## Checked at the start

Every key of the starter is checked when the application starts. An invalid value (`spring.flutter.app.type=swing`), a misspelled theme key (`seed-colour`) or a shortcut no notation reads stops the start. `SpringApplicationWidget` then shows its failure screen and logs the report, naming the property, the value and what is allowed, often with a "did you mean". Nothing is ignored silently: the theme properties of a design whose starter is not in the application (`components`, `cupertino`, ...) are accepted, not checked, and named once in the log (see [Theme properties](themes/properties.md)).

The generator also writes the starter's metadata, so editors with completion offer every key with its type and description (see [Metadata for editors](../spring-core-dart-generator/metadata.md)).

## A real configuration

A site built with these starters (the one you are reading) uses three files:

```yaml
# lib/resources/application.yml (part)
spring:
  config:
    import: resources:themes/neon.yml
  flutter:
    app:
      type: widgets
      title: Spring for Dart
      description: Spring's programming model for Dart and Flutter.
      debug-banner: false
    shortcuts:
      search.open: [primary+k, slash]
    web:
      dev-server:
        port: 5110
        host: 127.0.0.1
    theme:
      source: github:farum-azula/themes/themes/code.yml@code-v0.2.0
      active: system
      system-light: spring-dart-light
      system-dark: spring-dart
```

```yaml
# lib/resources/application-web.yml (part): only a browser reads it
spring:
  flutter:
    splash:
      warm-up:
        text:
          enabled: true
    web:
      page:
        swipe-to-close: false
        max-pixel-ratio: 2
        translate: false
```

```yaml
# lib/resources/application-release.yml: only release builds read it
logging:
  level:
    root: warn
```

## See also

- [Configuration in spring_core_dart](../spring-core-dart/config/index.md)
- [Profiles](../spring-core-dart/config/profiles.md)
- [Placeholders](../spring-core-dart/config/placeholders.md)
- [All properties](properties.md)
- [Themes](themes/index.md)
