
# 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 `Resource`s, 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

```dart
// 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 an `AssetResource` of `rootBundle`. An `AssetBundle` bean replaces `rootBundle`, in tests for example.
- `asset:/assets/x.png` works too, and so does `context.getResource('asset:...')`.
- `exists()` looks the key up in the app's asset manifest, which `SpringApplicationWidget` loads before the start.
- `asset:` also works as a configuration location: `spring.config.import: asset:config/app.yml`.
- `@Resource` is 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:

```yaml
# lib/resources/application.yml
spring:
  resources:
    embed:
      exclude: [content/**, images/**]
```

```yaml
# 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](../spring-core-dart-generator/resources.md#leaving-files-out-of-the-binary).

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

```text
@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:

```yaml
# pubspec.yaml
flutter:
  assets:
    - assets/fonts/          # Inter-Regular.ttf, Inter-SemiBold.ttf, JetBrainsMono.ttf
```

```yaml
# 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 `.ttc` collection, 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](themes/typography.md#a-font-for-a-language).

On the web, characters the app's fonts lack are drawn with fonts Flutter downloads; see [the font warm-up](splash.md#fonts-for-the-apps-text).

## In Spring (Java)

`@Value("classpath:...")` injects a `ClassPathResource`; here `resources:` is the classpath and `asset:` adds Flutter's asset bundle.

## See also

- [Resources in spring_core_dart](../spring-core-dart/resources/index.md)
- [Typography](themes/typography.md)
- [Embedded resources](../spring-core-dart-generator/resources.md)
