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:

The rules are the ones of Spring Boot, so the configuration pages of spring_core_dart apply here too. This page lists what is special in a Flutter app.

The files

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)

The same settings in both formats:

# 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
# 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 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). An app without a design library is of type widgets and sets its colors under colors.* (see Design libraries).

The spring.* keys configure the framework; All properties lists those of this starter. The shop.* keys are your own, read with @Value or a @ConfigurationProperties class (see 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.

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:

// 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:

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

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 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:

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

# lib/resources/application.yml
spring:
  config:
    import:
      - resources:themes/ocean.yml
      - resources:themes/neon.yml
      - optional:resources:local.yml   # 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)
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:

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

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

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.

# 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)
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 from your own server SpringThemes.loadYaml(yaml) in code Whenever your code calls it (see Themes)

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:

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

The OS environment

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

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)

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:

// 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 and @Value.

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

The generator also writes the starter's metadata, so editors with completion offer every key with its type and description (see Metadata for editors).

A real configuration

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

# 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/[email protected]
      active: system
      system-light: spring-dart-light
      system-dark: spring-dart
# 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
# lib/resources/application-release.yml: only release builds read it
logging:
  level:
    root: warn

See also