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.
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
# 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:
# 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.pngmatches/*and/assets/*:max-age=2592000, public./assets/AssetManifest.bin.jsonmatches/*,/assets/*and/assets/AssetManifest*:no-cache.- The block has the last word over the app's rules before it: its
/*takes off theirCache-Control. Their other headers (X-Frame-Options, aContent-Security-Policy) stay. - An app's rule after the block has the last word over it. That is the place for
immutableon files whose names change with their content; there is no key for it, as on the server.
# 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_flutterand has aweb/index.html. It reads the configuration as the app reads it in a browser:application.*, thenapplication-web.*, and the files of the profilesspring.profiles.activenames there.--dart-definevalues do not count. - The markers. The block runs from
# spring:cache:startto# 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
falseones), 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.
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.