Opt-in V8 explicit compile hints for first-load chunks

[AdzerKI]

Goals

1. Let an app opt in to V8's file-level explicit compile hint, //# allFunctionsCalledOnLoad, on the client chunks every page runs at startup. Chrome 136+ then compiles their functions on the background thread that streams the script, instead of lazily on the main thread while hydration calls them.
2. Make the hint correct by construction: first line of the emitted chunk, covered by the chunk's content hash, source maps shifted by one line, SRI digests computed over the hinted bytes.
3. Support Turbopack.

Non-Goals

1. Per-function hints or profile-guided selection of functions.
2. Hinting chunks that load only through dynamic imports or client navigation.
3. Turning it on by default before there's data from more apps.

Background

Today the only way is a post-build step. Ours reads rootMainFiles from build-manifest.json and entryJSFiles from each page's client reference manifest, prepends the hint to those chunks, then rewrites their digests in subresource-integrity-manifest.json and in prerendered HTML. It depends on internal manifest formats, and it can't change the hashed file name, so hinted bytes reuse the URL of unhinted bytes that browsers may hold as immutable. Chrome and V8 have no flag that does the same for a site.

Prior art: cloudflare/vinext#4247 hints the static closure of the browser entries in vinext.

Results on a production App Router site (Next.js 16.4, Turbopack). Same build, hint stripped from chunks by request interception in the "without" runs. Cold load in headless Chromium, 4x CPU throttle, median of 7 runs, ms. TBT here is long tasks after FCP until the main thread is idle after hydration.

page	TBT without → with	hydrated without → with
home	971 → 510	2567 → 2316
category listing	1043 → 515	2547 → 2286
product page	1069 → 440	2814 → 2303

LCP moved 920 → 864 on home and 2612 → 2156 on the product page. The load event didn't change.

Proposal

An opt-in flag, e.g. experimental.compileHints: true. When it's set, the build prepends //# allFunctionsCalledOnLoad to the chunks a page needs at first load: the root main files and the evaluated chunk group of each page entry. In Turbopack the hint would be part of chunk code generation, so the content hash, the source map offset and the SRI digest all see the final bytes. Chunks reached only through dynamic imports stay lazy, since V8 advises using the hint sparingly.

I'm happy to send a PR once the shape of the option is agreed.

[fedyfsgerana]

I think this is a solid proposal, and I agree that compile hints should be integrated directly into the chunk generation process rather than handled by a post-build script.

One important consideration is ensuring that the hint is only added to chunks that are guaranteed to be loaded during the initial page load. This would help avoid unnecessary compilation overhead for chunks that are not immediately needed.

I also think source map offsets, content hashes, and SRI digests should all be generated from the final emitted chunk content to ensure consistency and prevent caching issues.

For Turbopack, it would be important to apply the hint before chunk hashing and source map generation, so both bundlers produce consistent results.

One question worth exploring is whether shared chunks used by multiple page entries can be identified and hinted without accidentally including chunks that are only needed for dynamic imports.

Overall, an opt-in experimental flag makes sense. I would support moving forward with this proposal, provided the implementation includes tests for both Webpack and Turbopack, along with production benchmarks across different applications.

[AdzerKI]

Thanks! On shared chunks: the evaluated chunk group of a page entry already holds the shared chunks that page runs at startup, so they get the hint with the rest of the group. Chunks reachable only through import() sit in async chunk groups and stay lazy. Agreed on tests and more benchmarks before anything is on by default.