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

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/

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

See also