
# The browser cache of a web build

A Flutter web build is plain files, and a static host tells browsers how long to keep them through its headers file. When a `spring.web.resources.cache.cachecontrol.*` key is set, every `build_runner` build writes the cache rules into the app's `web/_headers`, the headers file of Cloudflare Pages: the files of the build are asked for again on every open, and the app's images and fonts are kept as the keys say. The keys are Spring Boot's, the same that set `Cache-Control` on a server's [static resources](../spring-boot-starter-web/static-resources.md).

## Why

A Flutter web build names its files without a hash: `index.html`, `main.dart.js`, `main.dart.wasm`, `flutter_bootstrap.js`, the asset manifests. A browser that kept them would run an old build after a deploy, so they need `no-cache`. The app's own images and fonts under `/assets/` change seldom and may be kept for days. A headers file written by hand usually gets one of the two wrong: `no-cache` on every path downloads all the images again on every open, and a long `max-age` on every path keeps an old build.

## Example

```yaml
# lib/resources/application-web.yml
spring:
  web:
    resources:
      cache:
        cachecontrol:
          max-age: 30d
          cache-public: true
```

After `dart run build_runner build`, `web/_headers` has this block:

```text
# spring:cache:start
# Generated from spring.web.resources.cache.cachecontrol.* on every build: change the configuration, not these lines.
/*
  ! Cache-Control
  Cache-Control: no-cache
/assets/*
  ! Cache-Control
  Cache-Control: max-age=2592000, public
/assets/AssetManifest*
  ! Cache-Control
  Cache-Control: no-cache
/assets/FontManifest.json
  ! Cache-Control
  Cache-Control: no-cache
/assets/NOTICES
  ! Cache-Control
  Cache-Control: no-cache
/assets/*/manifest.json
  ! Cache-Control
  Cache-Control: no-cache
/assets/shaders/*
  ! Cache-Control
  Cache-Control: no-cache
/assets/fonts/MaterialIcons-Regular.otf
  ! Cache-Control
  Cache-Control: no-cache
/assets/packages/cupertino_icons/*
  ! Cache-Control
  Cache-Control: no-cache
/assets/lib/resources/*
  ! Cache-Control
  Cache-Control: no-cache
# spring:cache:end
```

`flutter build web` copies `web/` into `build/web/`, so the file lands at the root of what you deploy, where the host reads it.

## What gets what

| Paths | `Cache-Control` | Why |
|---|---|---|
| `/*`: the page, `main.dart.js`, `main.dart.wasm`, `flutter_bootstrap.js`, `manifest.json`, everything outside `/assets/` | `no-cache` | The same names in every build. The browser asks each time and gets a `304` without a body while nothing changed, so a deploy is seen at once |
| `/assets/*`: the app's images, fonts and other assets | the value the keys build | They change seldom |
| `/assets/AssetManifest*`, `/assets/FontManifest.json`, `/assets/NOTICES`, `/assets/*/manifest.json` | `no-cache` | The asset and font manifests, the licences and flutter_scene's shader manifests change with every build |
| `/assets/shaders/*` | `no-cache` | The engine's shaders, built with the app |
| `/assets/fonts/MaterialIcons-Regular.otf`, `/assets/packages/cupertino_icons/*` | `no-cache` | Flutter cuts the icon fonts down to the icons the app uses, under the same name every build: with a kept one, a new icon would show as a box |
| `/assets/lib/resources/*` | `no-cache` | The app's resources read at run time, not embedded in its code: Markdown pages, messages, a search index. They have no hash and change with the content, so a kept copy would show a page as it was before the deploy |

## How the rules combine

The host applies every rule whose path matches, in the order of the file. Each rule of the block starts with `! Cache-Control`, Cloudflare's way to take off the `Cache-Control` an earlier rule set, so a path gets the value of the last rule that matches it:

- `/assets/logo.png` matches `/*` and `/assets/*`: `max-age=2592000, public`.
- `/assets/AssetManifest.bin.json` matches `/*`, `/assets/*` and `/assets/AssetManifest*`: `no-cache`.
- The block has the last word over the app's rules before it: its `/*` takes off their `Cache-Control`. Their other headers (`X-Frame-Options`, a `Content-Security-Policy`) stay.
- An app's rule after the block has the last word over it. That is the place for `immutable` on files whose names change with their content; there is no key for it, as on the server.

```text
# The app's own rules.
/*
  X-Frame-Options: DENY

# spring:cache:start
...
# spring:cache:end

/fonts/*
  ! Cache-Control
  Cache-Control: max-age=31536000, immutable
```

## The block in the file

- **Who writes it.** The generator's page loader builder, in an app that depends on `spring_boot_starter_flutter` and has a `web/index.html`. It reads the configuration as the app reads it in a browser: `application.*`, then `application-web.*`, and the files of the profiles `spring.profiles.active` names there. `--dart-define` values do not count.
- **The markers.** The block runs from `# spring:cache:start` to `# spring:cache:end`; its first line says where it comes from. Every build writes it again, so change the configuration, not its lines.
- **Where.** Where the markers are; the first time, after the app's rules, with an empty line before it. A missing file is created. A second block is removed.
- **The rest is the app's.** The rules before and after the block are kept as they are.
- **The keys go, the block goes.** With no key set (or only `false` ones), the block is removed, and the file too when nothing else is in it.
- **A wrong value** (`max-age: 30 days`, `cache-public: maybe`) fails the build, naming the key, and leaves the file as it is.

## The keys

The value of `/assets/*` is built as Spring Boot builds the header for a server: `no-store` if set, else `no-cache`, else `max-age`; then `must-revalidate`, `no-transform`, `public`, `private`, `proxy-revalidate`, `s-maxage`, `stale-if-error` and `stale-while-revalidate`.

| Key | Type | Directive |
|---|---|---|
| `spring.web.resources.cache.cachecontrol.max-age` | duration | `max-age=<seconds>` |
| `spring.web.resources.cache.cachecontrol.no-cache` | bool | `no-cache`; wins over `max-age` |
| `spring.web.resources.cache.cachecontrol.no-store` | bool | `no-store`; wins over `no-cache` and `max-age` |
| `spring.web.resources.cache.cachecontrol.must-revalidate` / `no-transform` / `proxy-revalidate` | bool | The directive of the same name |
| `spring.web.resources.cache.cachecontrol.cache-public` / `cache-private` | bool | `public` / `private` |
| `spring.web.resources.cache.cachecontrol.s-max-age` | duration | `s-maxage=<seconds>` |
| `spring.web.resources.cache.cachecontrol.stale-while-revalidate` / `stale-if-error` | duration | The directive of the same name, in seconds |

A duration without a unit is seconds, as Spring Boot reads these keys (`3600`); `30d`, `2h` and `PT1H` work too, and the header gets whole seconds. `spring.web.resources.cache.period` and `use-last-modified` are not read here: only the `cachecontrol.*` keys make the block.

## Hosts

The block is written for Cloudflare Pages: `! Cache-Control`, which takes off an earlier rule's header, is Cloudflare's syntax. Netlify reads a `_headers` file too, but not those lines; there, and on hosts that read no `_headers` (GitHub Pages, Firebase Hosting), set the same rules in the host's own configuration. A Dart server that serves the build with `spring_boot_starter_web` sends `Cache-Control` itself, from the same keys, with one value for every file: see [Static resources](../spring-boot-starter-web/static-resources.md).

On a domain of its own the site is behind the zone's cache settings, which come after the file. With Caching → Configuration → Browser Cache TTL set to a time (4 hours, the default of older zones), Cloudflare puts that time in place of `no-cache` on the files it counts as static: scripts, images, fonts. `flutter_bootstrap.js`, `main.dart.js` (the build every browser but Chromium's runs, Flutter's default: Safari, Firefox and every browser on iOS) and the icon fonts are then kept up to that long after a deploy, and a phone shows the build before it. Set Browser Cache TTL to *Respect Existing Headers* (or a Cache Rule's browser TTL to the origin's), so the file decides. `curl -sI https://<site>/main.dart.js` then says `cache-control: no-cache`.

## In Spring (Java)

Spring has no counterpart: a Spring Boot server sends the header itself. Here the same keys reach a static host that runs no Spring code.

## See also

- [The web](web.md)
- [Static resources](../spring-boot-starter-web/static-resources.md)
- [Resources from the network](resources.md)
- [Properties the build reads](../spring-core-dart-generator/build-properties.md)
- [All properties](properties.md)
