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 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)
- No
pubspec.yamlentry. The generator embeds every file oflib/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
.propertiesmean the same thing. Use either, or both. When one place has both,.propertieswins over.yml, which wins over.yaml. resources:points intolib/resources/.resources:themes/ocean.ymlislib/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 watchrewrites that code when you save one, and the next hot reload restarts the context with the new values (see Hot reload).
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
- An imported file wins over the file that imports it, and it gets its own profile variants:
themes/ocean-web.ymlis 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) |
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
- A define is read like an environment variable in Spring Boot:
SHOP_API_URLanswersshop.api-urland@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, becauseString.fromEnvironmentneeds a constant name. It writes every name the app can read: the${...}placeholders of annotations, the fields of@ConfigurationPropertiesclasses, the keys of the configuration files, and a few such asspring.profiles.active. A define of any other name is not seen. See --dart-define keys. - 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:
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:
springBootTest(properties: ...)in testsSpringApplicationWidget(args: ...)--dart-definevalues- OS environment variables (only with
spring.flutter.scan-os-environment=true) - 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);
.propertiesabove.ymlabove.yaml; a later document above an earlier one SpringApplication(defaultProperties: ...)- 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