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:

# 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

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.

See also