[HOLD - Q4 Release] Add caching and Cache-Control header guidance to Web Deployment documentation
- Dominant language
- Dart
- Stars
- 3.1k
- Forks
- 3.5k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 95
Description
> [!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](https://github.com/flutter/flutter/issues/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](https://github.com/flutter/flutter/issues/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..js`, `main.dart..wasm`, `main.dart..mjs`, `main.dart..js.map`, `main.dart..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).
Contributor guide
Research direction
This issue targets the Web deployment page at docs.flutter.dev/deployment/web and depends on the experimental --web-content-hash feature tracked in flutter/flutter#149031. Start by reviewing the page and the feature's Phase 1 status after the Q4 stable release is finalized. Done means adding the caching guidance and Firebase Hosting, Netlify, and Nginx examples described here without merging while the issue remains on hold.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- firebase, nginx
- Domain
- devops, documentation, web-dev
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100