feat(web): support --web-content-hash for entrypoint files by kevmoo · Pull Request #190153 · flutter/flutter

kevmoo · 2026-07-28T17:38:53Z

Enables content-hashed filenames for web build outputs (main.dart.<hash>.js, .wasm, .mjs) via the optional --web-content-hash flag in flutter build web.

Adds typed WebOptions.webContentHash descriptor to WebCoreOptionsBundle.
Implements _hashAndRenameWebOutput in web.dart to compute SHA-256 digests of compiled entrypoint binaries and rename outputs on disk.
Dynamically discovers hashed entrypoint URLs in Dart2WebTarget.getBuildConfig and embeds them into flutter_bootstrap.js.
Preserves unhashed main.dart.wasm.map to maintain WebAssembly binary sourceMappingURL custom section integrity.
Unconditionally prunes stale entrypoint files from build/web/ across repeated builds.
Fast-fails build if web/index.html contains direct <script src="main.dart.js"> tags or deprecated FlutterLoader.loadEntrypoint calls.
Emits post-build serving tip linking to web deployment caching guidance.

Fixes #191914
Part of #149031

gemini-code-assist

Code Review

This pull request introduces a --web-content-hash flag to the Flutter web build command, which appends content hashes to the filenames of web output files (such as JavaScript, WebAssembly, and source maps) to prevent caching issues. The review feedback highlights a critical issue where attempting to read binary .wasm files as UTF-8 strings to update source map references causes performance bottlenecks and failures. Additionally, renaming .wasm.map files breaks the internal sourceMappingURL reference inside the .wasm binary. The feedback suggests keeping .wasm.map files unhashed, skipping string replacement on .wasm binaries, and updating the build targets and pattern stems accordingly.

flutter-dashboard · 2026-08-26T17:22:04Z

This pull request is not mergeable in its current state, likely because of a merge conflict. Pre-submit CI jobs were not triggered. Pushing a new commit to this branch that resolves the issue will result in pre-submit jobs being scheduled.

Include an 8-character content hash in the filenames of compiled web entrypoints (for example, 'main.dart.<hash>.js', 'main.dart.<hash>.wasm', 'main.dart.<hash>.mjs', and paired source maps) so web servers can serve executable assets with 'Cache-Control: max-age=31536000, immutable'. * Register typed 'WebOptions.webContentHash' flag descriptor in 'WebCoreOptionsBundle'. * Validate 'web/index.html' during 'build web' and fast-fail if legacy direct 'main.dart.js' script tags or deprecated 'FlutterLoader.loadEntrypoint' APIs are present. * Hash and rename dart2js and dart2wasm outputs, update source map comments, and rewrite 'dart2js.d' and 'dart2wasm.d' depfiles. * Preserve unhashed 'main.dart.wasm.map' to maintain WASM binary section integrity. * Dynamically discover hashed entrypoints in 'Dart2WebTarget.getBuildConfig' and inject them into 'flutter_bootstrap.js'. * Prune stale hashed entrypoint files from 'build/web/' across repeated builds. * Emit serving tip linking to web deployment caching guidance.

* Scan 'compileTargets' directly in 'WebTemplatedFiles.buildConfigString' to ensure 'wasmHashes' is accurately populated on clean builds before outputs are copied. * Harden 'Dart2JSTarget.getBuildConfig' and 'Dart2WasmTarget.getBuildConfig' to safely resolve entrypoints when residual or unhashed files exist in buildDir. * Unconditionally clean up stale entrypoints in 'WebReleaseBundle.build' across both hashed and unhashed builds to prevent service worker cache pollution. * Scope sourceMappingURL comment rewriting to the trailing directive line. * Use 'project.web.indexFile' and filter HTML comments during index.html validation. * Support compound extensions like '.js.map' in '_computeHashedBasename'.

…motion

kevmoo · 2026-08-27T21:44:18Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces the --web-content-hash flag to include content hashes in compiled web entrypoint filenames, preventing browsers from serving stale cached files. It implements renaming logic, updates target configurations, handles cleanup of outdated entrypoints, and adds comprehensive tests. The review feedback identifies two opportunities to improve cleanup: first, by removing stale .part.js and .part.js.map files from the build directory to avoid false-positive tool exits on subsequent builds; and second, by updating _entrypointFileRegex to match and clean up deferred Wasm modules when switching build configurations.

…er --web-content-hash

…ase-1

…ster merge

…itive complexity

…within 100-char GA4 limit

- Guard against non-existent build directory and sort by last modified time in _resolveHashedBasename - Anchor _partFileRegex with $ and reuse static _partFileMapRegex in buildFiles - Scope CanvasKit WASM exclusion to relative buildDir path to avoid ancestor directory collisions - Extend _entrypointFileRegex to match deferred part files during cleanup - Use inherited logger.printStatus in BuildWebCommand - Add unit tests for candidate sorting, canvaskit path scoping, and part file cleanup

Roll Flutter from 63b9518f16bc to 2553f89be1ef (62 revisions) flutter/flutter@63b9518...2553f89 2026-09-12 [email protected] Roll clang to 07d67299a15ce03b053736e2d31a668ee0576987 (flutter/flutter#192607) 2026-09-12 [email protected] Roll Dart SDK from b24b352c29db to 7863887acbfb (3 revisions) (flutter/flutter#192665) 2026-09-12 [email protected] fix(tree): et format --all (flutter/flutter#192669) 2026-09-12 [email protected] Support activity-alias in Android launcher activity detection (flutter/flutter#187251) 2026-09-12 [email protected] fix: regenerate gradle lockfiles for external_textures integration test (flutter/flutter#192657) 2026-09-12 [email protected] Roll Skia from 51aa02b2c195 to e5e96533b732 (4 revisions) (flutter/flutter#192646) 2026-09-12 [email protected] [WebParagraph] Fix text pixelation, glyph clipping, and snapping offsets to avoid subpixel raster caching (flutter/flutter#191736) 2026-09-12 [email protected] fix(tests): Add ruby dep to Mac windowing_test (flutter/flutter#192656) 2026-09-12 [email protected] Remove some `unawaited_futures` outdated ignores (flutter/flutter#192026) 2026-09-11 [email protected] Bump Dart to 3.13, reformat, re-enable formatting check (flutter/flutter#192649) 2026-09-11 [email protected] [android] Isolate API-34 high contrast listener in AccessibilityBridge behind Api34Impl (flutter/flutter#192502) 2026-09-11 [email protected] Update style guide for Dart 3.13 (flutter/flutter#192639) 2026-09-11 [email protected] ci(bringups): remove bringup from these tests (flutter/flutter#192637) 2026-09-11 [email protected] Unmark new_gallery_windows_impeller__transition_perf as bringup (flutter/flutter#192633) 2026-09-11 [email protected] Unmark new_gallery_windows_skia__transition_perf as bringup (flutter/flutter#192635) 2026-09-11 [email protected] Roll Skia from f446aec4ce9e to 51aa02b2c195 (2 revisions) (flutter/flutter#192631) 2026-09-11 [email protected] fix(ci): mac verify binaries still racing (flutter/flutter#192634) 2026-09-11 [email protected] Roll Packages from 8a35b16 to 9caa77c (8 revisions) (flutter/flutter#192630) 2026-09-11 [email protected] Roll Dart SDK from a76fee2722e0 to b24b352c29db (2 revisions) (flutter/flutter#192627) 2026-09-11 [email protected] [tool] Migrate PackagesCommand and Pub to modular dependency injection (flutter/flutter#192460) 2026-09-11 [email protected] [tool] Migrate Darwin framework commands to modular dependency injection (flutter/flutter#192252) 2026-09-11 [email protected] [tool] Migrate Upgrade, Downgrade, and UpdatePackages commands to modular dependency injection (flutter/flutter#190787) 2026-09-11 [email protected] Roll Skia from b3fa80a0e168 to f446aec4ce9e (55 revisions) (flutter/flutter#192620) 2026-09-11 [email protected] Roll Dart SDK from d20d59cfa664 to a76fee2722e0 (2 revisions) (flutter/flutter#192616) 2026-09-11 [email protected] remove deeplink integration tests from bringup (flutter/flutter#192459) 2026-09-11 [email protected] Revert: [devicelab] Clean up Chrome profile directories and trap abort signals in web benchmarks (flutter/flutter#192615) 2026-09-11 [email protected] Roll Fuchsia Linux SDK from C0j8F-_Iy-OQZ6YyI... to m69nfK-wnHaMTe8P9... (flutter/flutter#192608) 2026-09-11 [email protected] Fix Wasm build cache mismatch in ResidentWebRunner and browser 404 fallbacks (flutter/flutter#190786) 2026-09-11 [email protected] Roll Dart SDK from 3ce3116bc9ec to d20d59cfa664 (1 revision) (flutter/flutter#192588) 2026-09-11 [email protected] [Linux] Keep the frame at the top of a resizing subsurface (flutter/flutter#192408) 2026-09-10 [email protected] [devicelab] Clean up Chrome profile directories and trap abort signals in web benchmarks (flutter/flutter#192584) 2026-09-10 [email protected] [web] Keep ImageSource alive until Picture disposal (flutter/flutter#192516) 2026-09-10 [email protected] Remove the accessibility evaluations feature flag (flutter/flutter#192266) 2026-09-10 [email protected] Promote Windows gradient benchmark tests to non-bringup (flutter/flutter#192581) 2026-09-10 [email protected] Remove commented out export in `text_input.dart` since the dart compiler has the correct behavior now (flutter/flutter#191539) 2026-09-10 [email protected] [flutter_tools] Do not mistake server-initiated requests for responses to client requests in AnalysisServer (flutter/flutter#192546) 2026-09-10 [email protected] Roll Packages from 36e088a to 8a35b16 (12 revisions) (flutter/flutter#192550) 2026-09-10 [email protected] Roll pub packages (flutter/flutter#192517) 2026-09-10 [email protected] feat(web): support --web-content-hash for entrypoint files (flutter/flutter#190153) 2026-09-10 [email protected] [web] Stop iOS auto-zoom by sizing semantic inputs at 16px (flutter/flutter#192328) 2026-09-10 [email protected] Roll Dart SDK from 0d55b7a6a9ee to 3ce3116bc9ec (2 revisions) (flutter/flutter#192534) 2026-09-10 [email protected] Update more enum instances comparison to use equality == since dart has the correct behavior now (flutter/flutter#191788) 2026-09-10 [email protected] Fix specify_nonobvious_local_variable_types lints in luci_resultdb_test.dart (flutter/flutter#192543) 2026-09-10 [email protected] Roll ICU from 8cc91d9b6ab9 to 6ebb40c59477 (1 revision) (flutter/flutter#192527) 2026-09-10 [email protected] [Linux] Make the framebuffer depth/stencil buffer optional (flutter/flutter#192156) 2026-09-10 [email protected] [Linux] Cancel input when events stop being delivered (flutter/flutter#192277) ...

…lutter#192663) `--web-content-hash` currently hashes only the compiled entrypoints (flutter#191914). Static assets (flutter#191915), the service worker precache manifest (flutter#191916), and deferred loading parts (flutter#191917) are all still unhashed, so a build with the flag enabled can continue to serve stale cached content. Advertising the flag now sets an expectation the implementation does not yet meet. The flag has not shipped in any release. It landed on master in flutter#190153 on 2026-09-10, after the flutter-3.48-candidate.0 fork, so hiding it costs nothing today. It also avoids committing to the flag's boolean shape before the remaining phases show whether granularity is needed. Locks the behavior into the existing `flutter build web option visibility` tests, including the verbose-help variant, so the flag stays hidden rather than becoming verbose-only by accident. Un-hide once flutter#191915 and flutter#191916 have landed.

github-actions Bot added the tool Affects the "flutter" command-line tool. See also t: labels. label Jul 28, 2026

kevmoo changed the title ~~web content hash phase 1~~ feat(web): support --web-content-hash for entrypoint files Jul 28, 2026

kevmoo marked this pull request as ready for review August 12, 2026 07:18

kevmoo requested a review from a team as a code owner August 12, 2026 07:18

kevmoo requested review from jesswrd and removed request for a team August 12, 2026 07:18

gemini-code-assist Bot reviewed Aug 12, 2026

View reviewed changes

Comment thread packages/flutter_tools/lib/src/build_system/targets/web.dart Outdated

Comment thread packages/flutter_tools/lib/src/build_system/targets/web.dart

Comment thread packages/flutter_tools/lib/src/build_system/targets/web.dart

kevmoo force-pushed the web-content-hash-phase-1 branch from d5ee436 to 57cec35 Compare August 12, 2026 07:24

jesswrd added the CICD Run CI/CD label Aug 26, 2026

kevmoo force-pushed the web-content-hash-phase-1 branch from 588414b to 31a2383 Compare August 27, 2026 20:02

kevmoo requested a review from mdebbar August 27, 2026 20:24

kevmoo mentioned this pull request Aug 27, 2026

[deployment/web] Add --web-content-hash, Cache-Control, Overlay Deployment, and precache_manifest.json guidance for Flutter 3.50 flutter/website#13825

Open

fix(web): update deployment guidance docs URL in serving tip

a540e7d

kevmoo commented Aug 27, 2026

View reviewed changes

Comment thread packages/flutter_tools/lib/src/commands/build_web.dart Outdated

chore(web): add TODO tracking flutter/website#13825 before stable pro…

4c82185

…motion

This was referenced Aug 27, 2026

[web] Support content-hashed entrypoint filenames (--web-content-hash) #191914

Closed

[WEB] ☂️ Web Cache invalidation based on pubspec.yaml version #149031

Open

gemini-code-assist Bot reviewed Aug 27, 2026

View reviewed changes

Comment thread packages/flutter_tools/lib/src/build_system/targets/web.dart Outdated

Comment thread packages/flutter_tools/lib/src/build_system/targets/web.dart

kevmoo added 7 commits September 6, 2026 03:25

fix(web): clean up stale .part.js files and deferred wasm modules und…

b6152e5

…er --web-content-hash

Merge remote-tracking branch 'origin/master' into web-content-hash-ph…

b150ec4

…ase-1

test(web): use createFakeBuildCommand in build_web_test.dart after ma…

5375a19

…ster merge

refactor(web): extract helpers to improve readability and reduce cogn…

05a8344

…itive complexity

refactor(web): use package:path extension and segment logic in web.dart

9e87f9e

style(web): fix local variable type annotation lints in web.dart

0daf00e

fix(web): omit webContentHash from buildEventAnalyticsValues to stay …

253127f

…within 100-char GA4 limit

mdebbar reviewed Sep 9, 2026

View reviewed changes

mdebbar approved these changes Sep 10, 2026

View reviewed changes

kevmoo added the autosubmit Merge PR when tree becomes green via auto submit App label Sep 10, 2026

auto-submit Bot added this pull request to the merge queue Sep 10, 2026

Merged via the queue into flutter:master with commit f798084 Sep 10, 2026
23 checks passed

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Sep 10, 2026

Renzo-Olivares mentioned this pull request Sep 11, 2026

Flutter Notable Commits - 2026 #181433

Open

kevmoo mentioned this pull request Sep 12, 2026

fix(web): hide --web-content-hash until content hashing is complete #192663

Merged

This was referenced Sep 12, 2026

Roll Flutter from 63b9518f16bc to 2553f89be1ef (62 revisions) flutter/packages#12853

Closed

Roll Flutter from 63b9518f16bc to 2553f89be1ef (62 revisions) flutter/packages#12855

Merged

kevmoo mentioned this pull request Sep 22, 2026

Web App Subresource Integrity (SRI) and enable more secure Content Security Policies (CSP) #185936

Open

kevmoo deleted the web-content-hash-phase-1 branch September 22, 2026 05:04

jfrazx mentioned this pull request Oct 6, 2026

Long-lived caching for the web client's content-hashed files BoardGamesEmpire/board-games-empire-backend#653

Open

Navigation Menu

Repository navigation

feat(web): support --web-content-hash for entrypoint files - #190153

feat(web): support --web-content-hash for entrypoint files#190153
auto-submit[bot] merged 13 commits into
flutter:masterfrom
kevmoo:web-content-hash-phase-1

kevmoo commented Jul 28, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flutter-dashboard Bot commented Aug 26, 2026

Uh oh!

Uh oh!

kevmoo commented Aug 27, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

kevmoo commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flutter-dashboard Bot commented Aug 26, 2026

Uh oh!

Uh oh!

kevmoo commented Aug 27, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kevmoo commented Jul 28, 2026 •

edited

Loading