[HOLD - Q4 Release] Add caching and Cache-Control header guidance to Web Deployment documentation

[kevmoo]

Warning

DO NOT WORK ON OR MERGE THIS DOC ISSUE YET.
This issue tracks documentation updates for the experimental --web-content-hash feature in Flutter Web (Umbrella Issue: flutter/flutter#149031).

Implementation is currently in Phase 1 (executable entrypoints only). Do not draft or merge documentation updates on docs.flutter.dev until the upcoming Q4 stable release is finalized and the feature has matured.

Page URL

https://docs.flutter.dev/deployment/web

Problem

With the introduction of content-hashed web entrypoints in the Flutter build system (flutter build web --web-content-hash, flutter/flutter#149031), the Flutter Web deployment guide will need guidance on configuring web server and CDN Cache-Control response headers.

Without explicit server header configuration:

1. Serving index.html or flutter_bootstrap.js with long-term cache headers causes browsers to retain stale application manifests across deployments.
2. Serving hashed executable assets without Cache-Control: immutable forces redundant network revalidations on every user visit.

Proposed Content

Add a dedicated "Web server and CDN caching configuration" section to https://docs.flutter.dev/deployment/web covering:

1. Bootstrap & Manifest Files (Revalidate):

   • Files: index.html, flutter_bootstrap.js, manifest.json, version.json
   • Header: Cache-Control: no-cache, must-revalidate (or max-age=0, must-revalidate)
   • Rationale: Ensures browsers fetch the latest bootstrap manifest on each visit to discover new deployment hashes immediately.

2. Hashed Executable Binaries (Immutable):

   • Files: main.dart.<hash>.js, main.dart.<hash>.wasm, main.dart.<hash>.mjs, main.dart.<hash>.js.map, main.dart.<hash>.mjs.map
   • Header: Cache-Control: public, max-age=31536000, immutable
   • Rationale: Unique content hashes guarantee filename uniqueness per build, allowing browsers and CDNs to cache executables permanently.

3. Unhashed Static Assets & Wasm Source Maps (Moderate TTL):

   • Files: assets/*, canvaskit/*, flutter.js, and main.dart.wasm.map
   • Header: Cache-Control: public, max-age=3600, must-revalidate (or appropriate CDN cache profile)
   • Rationale: In Phase 1 of web content hashing, asset bundles and Wasm source maps (which embed unhashed custom section pointers) retain fixed filenames across builds and require regular revalidation.

4. Example Hosting Configurations:

   • Include sample configuration snippets for common hosting providers (Firebase Hosting firebase.json headers block, Netlify _headers, and Nginx server blocks).

[uldall]

It would also be helpful to add documentation on how to handle new releases.

IMHO the issue that needs handling is the following:

• Client A downloads index.html (and flutter_bootstrap.js) which references main.dart.<hash>.js.
• The server is updated with a new release of the Flutter application by deleting the files of the old release and adding the files of the new release.
• Client A tries to download main.dart.<hash>.js, but the file no longer exists because the hash has changed in the new release.

This problem also exists in a related manner even without the hash as files might have been updated between two releases, and now Client A will be downloading a "frankenstein" application that is a mixture of two releases.

I believe this can potentially be solved by using --base-href and storing all previous releases of the application next to the new release. In this way index.html of Version X will only reference files in for example base /version-X/ and things should work fine. If I have understood things correctly, this however beats the purpose of the hash being added to files.

Is the solution to blend all releases of the Flutter application into a single folder on the web server? I.e. such that main.dart.hash A.js exists next to main.dart.hash B.js?