Assets and fonts
A Flutter app has two places for files, as a Spring app has src/main/resources and its static content. Both are read as Spring Resources, so a bean that reads a file does not care where it comes from. Font files among the assets are loaded by themselves, into the family the file names.
lib/resources/ |
Flutter assets (flutter: assets: in pubspec.yaml) |
|
|---|---|---|
| for | configuration, messages, small texts and templates | images, video, sound, large data, fonts |
| how | embedded into the generated code by default (up to 1 MB per file); spring.resources.embed.exclude leaves files out, to be read as assets |
in the app's asset bundle, loaded when read |
| location | resources:mail/welcome.txt |
asset:assets/intro.mp4 |
| reading | synchronous or asynchronous | asynchronous |
Why
Reading assets through rootBundle ties a service to Flutter and makes it hard to test. As a Resource injected with @Value, the same bean reads an asset in the app and a fake in a test. And a misspelled asset path fails the build, not the app in front of a user.
Example
// The About screen's logo and text.
@Component()
class AboutContent {
AboutContent(
@Value('asset:assets/images/logo.png') this.logo,
@Value('asset:assets/texts/about.md') this.text,
);
final Resource logo;
final Resource text;
Future<String> read() => text.readAsString();
// Flutter's image, video and audio APIs take the asset key.
ImageProvider get logoImage => AssetImage((logo as AssetResource).key);
}
asset: locations
asset:gives anAssetResourceofrootBundle. AnAssetBundlebean replacesrootBundle, in tests for example.asset:/assets/x.pngworks too, and so doescontext.getResource('asset:...').exists()looks the key up in the app's asset manifest, whichSpringApplicationWidgetloads before the start.asset:also works as a configuration location:spring.config.import: asset:config/app.yml.@Resourceis not for this: in Spring, and here, it injects a bean by name.
resources: and asset: work the same
Files of lib/resources/ and Flutter assets have the same features, so a page of Markdown can be either:
resources: |
asset: |
|
|---|---|---|
| read | readAsString, readAsBytes (async) |
the same |
exists() |
embedded files, or the asset manifest | the asset manifest |
| patterns | resources:content/**/*.md |
asset:docs/**/*.md |
| relative links between Markdown pages | yes | yes |
| pages for search engines | yes | yes |
| search | spring.search.markdown[n].location |
the same, with an asset: location |
AssetResource is a ContextResource: pathWithinContext is its path in the root it was found in. SpringApplicationWidget registers the assets as resource roots (AssetResourceRoot) when it has the app's asset manifest, so the patterns list them. The only difference is that synchronous reads (readAsStringSync) work for embedded files only; use the asynchronous ones.
A file can be put anywhere under flutter: assets: and read as asset:path, or kept in lib/resources/ and read as resources:. By default the build embeds every file of lib/resources/ in the binary: reads are instant, and it works on every platform without declaring assets. spring.resources.embed.exclude leaves files out of the binary:
# lib/resources/application.yml
spring:
resources:
embed:
exclude: [content/**, images/**]
# pubspec.yaml
flutter:
assets:
- lib/resources/content/
- lib/resources/content/docs/
- lib/resources/images/
- The same
resources:locations keep working: the app reads the files as assets. In a mobile or desktop app they are inside the package; on the web a file is downloaded only when it is read. - A Flutter asset directory includes only its own files, not those of its subdirectories, so list each directory. The build prints the exact lines to add when one is missing.
- The configuration (
application*.yml,application*.properties, any.properties,config/) is always embedded. - Small files read at the start belong in the binary. Many or big files read on demand (documentation pages, pictures) belong in the assets.
For this documentation site, leaving the pages out took main.dart.wasm from 11.6 MB to 3.7 MB (about 1 MB compressed) and the JavaScript fallback from 14.5 MB to 4.2 MB. Opening a page downloads its 2 Markdown files instead of carrying all 834. See Embedded resources.
Checked at build time
The generator checks every @Value('asset:...'). A missing file, or one not declared under flutter: assets:, fails the build with the lines to add:
@Value('asset:assets/sounds/tap.mp3') in ...#Sounds: assets/sounds/tap.mp3 is
not declared in pubspec.yaml, so the app would not contain it. Add it under
`flutter: assets:`:
flutter:
assets:
- assets/sounds/
A directory entry (- assets/sounds/) takes in the files of that directory, but not those of its subdirectories (as in Flutter). Keys with placeholders (asset:${sound.file}) and other packages' assets (asset:packages/...) are only known at run time and are not checked.
Fonts
Font files go into any directory under flutter: assets: and are listed nowhere else. When the application starts (behind the splash), the starter loads every .ttf and .otf file among the app's assets, into the family the file itself names (its name table): Inter-SemiBold.ttf becomes a weight of Inter. The theme then names families only:
# pubspec.yaml
flutter:
assets:
- assets/fonts/ # Inter-Regular.ttf, Inter-SemiBold.ttf, JetBrainsMono.ttf
# lib/resources/application.yml
spring:
flutter:
theme:
typography:
font-family: Inter
code: { font-family: JetBrains Mono, size: 13 }
fonts:
exclude: [assets/pdf/**] # fonts for PDFs, not for the screen
- Families declared under
flutter: fonts:keep working. - A family the theme names but neither the assets nor
flutter: fonts:have is logged as a warning. It may still be one of the platform's own fonts, such as.SF UI Text. - A file whose family cannot be read, such as a
.ttccollection, is skipped with a warning. - A font of a package is named with its package, as in Flutter:
packages/neon_ui/Space Grotesk.
| Key | Type | Default | Meaning |
|---|---|---|---|
spring.flutter.fonts.auto-load |
bool | true |
Loads every .ttf and .otf asset before the first frame. false: no font file is loaded this way; the fonts of flutter: fonts: still work |
spring.flutter.fonts.exclude |
list of globs (* within a directory, ** across directories) |
none | Font assets not to load, such as fonts only used to make PDFs |
spring.flutter.fonts.families.<family>.files |
list of assets | none | The files of a family declared by name (.ttf, .otf; .woff2 on the web), loaded into it; auto-load leaves them alone |
spring.flutter.fonts.families.<family>.languages |
list of language tags | none | The languages the family is for (ja; it covers ja-JP): loaded before the first frame when the app starts in one, else when it switches to one. None: at the start |
A font for one language (Japanese) is declared by name with its languages: the other languages never download it, and the web engine fetches no fallback fonts of its own, page after page, for the characters the main font lacks. Name it in typography.font-family-fallback; see typography.
On the web, characters the app's fonts lack are drawn with fonts Flutter downloads; see the font warm-up.
In Spring (Java)
@Value("classpath:...") injects a ClassPathResource; here resources: is the classpath and asset: adds Flutter's asset bundle.