feat: add `webpackPrefetch`/`webpackPreload`/`webpackFetchPriority` support for URL-based assets by 3ru · Pull Request #19695 · webpack/webpack

3ru · 2025-07-13T07:16:53Z

PR Description

This PR refreshes prefetch/preload support across Worker chunks and new URL() assets, aligns the behavior with dynamic import(), and introduces new runtime helpers.

fixes

fixes feat: support webpackPrefetch/webpackPreload/webpackFetchPriority for new Worker syntax #19377
fixes support webpackPrefetch and webpackPreload for new Worker() chunk #19373
fixes feat: support webpackPrefetch for new URL(...) #18524

What kind of change does this PR introduce?

Adds magic comment support to configure resource hints:

Worker chunks (numeric ordering + fetch priority)
new URL() assets (boolean flags + fetch priority + explicit preload attribute overrides)
Introduces runtime helpers to inject <link> elements at runtime:
prefetchAsset and preloadAsset

Supported magic comments

Worker chunks (new Worker / SharedWorker / service worker register):
- /* webpackPrefetch: true | number */
- /* webpackPreload: true | number */
- /* webpackFetchPriority: "high" | "low" | "auto" */
new URL() assets:
- /* webpackPrefetch: true */
- /* webpackPreload: true */
- /* webpackFetchPriority: "high" | "low" | "auto" */
- /* webpackPreloadAs: "<request-destination>" */
- /* webpackPreloadType: "<mime/type>" */
- /* webpackPreloadMedia: "<media-query>" */

Notes:

Worker accepts number ordering (same as import()), URL assets do not.
Explicit webpackPreloadAs/webpackPreloadType/webpackPreloadMedia override the auto-detected defaults for URL assets.
The as attribute accepts Fetch Standard request destinations. Allowed values include: audio, audioworklet, document, embed, fetch, font, image, manifest, object, paintworklet, report, script, sharedworker, serviceworker, style, track, video, worker, xslt.
Warnings are emitted for invalid values.

Example Usage

// Prefetch an asset for future use
const imageUrl = new URL(
  /* webpackPrefetch: true */
  './assets/hero.jpg',
  import.meta.url
);

// Preload with high priority
const criticalFont = new URL(
  /* webpackPreload: true */
  /* webpackFetchPriority: "high" */
  './fonts/main.woff2',
  import.meta.url
);

// Works with Worker syntax
const worker = new Worker(
  new URL(
    /* webpackPrefetch: true */
    './heavy-computation.worker.js',
    import.meta.url
  )
);

// Override as/type/media explicitly (defaults are auto-detected)
const fontUrl = new URL(
  /* webpackPreload: true */
  /* webpackPreloadAs: "font" */
  /* webpackPreloadType: "font/woff2" */
  /* webpackPreloadMedia: "(max-width: 600px)" */
  './fonts/heading.woff2',
  import.meta.url
);

// Accepts Fetch Request Destinations (e.g., sharedworker)
const helperUrl = new URL(
  /* webpackPreload: true */
  /* webpackPreloadAs: "sharedworker" */
  './scripts/worker-helper.js',
  import.meta.url
);

Did you add tests for your changes?

Yes

Does this PR introduce a breaking change?

No

What needs to be documented once your changes are merged?

Worker: true | number for webpackPrefetch/webpackPreload, fetchpriority supported.
URL:
- webpackPrefetch: true / webpackPreload: true
- webpackFetchPriority: "high" | "low" | "auto"
- Auto-detected as (based on file type), with explicit overrides:
  - webpackPreloadAs: "<request-destination>" (Fetch Request Destinations; includes audio, audioworklet, document, embed, fetch, font, image, manifest, object, paintworklet, report, script, sharedworker, serviceworker, style, track, video, worker, xslt)
  - webpackPreloadType: "<mime/type>"
  - webpackPreloadMedia: "<media-query>"
- Invalid values emit warnings.

rel

ESM Module Output #17121

codspeed-hq · 2025-07-13T07:44:36Z

CodSpeed Performance Report

Merging #19695 will improve performances by 20.58%

_{Comparing 3ru:feature/worker-prefetch-preload-support (aaae36e) with main (42ed7bc)}

Summary

⚡ 1 improvement
✅ 68 untouched

Benchmarks breakdown

	Benchmark	`BASE`	`HEAD`	Change
⚡	`benchmark "json-modules", scenario '{"name":"mode-development-rebuild","mode":"development","watch":true}'`	40.4 ms	33.5 ms	+20.58%

3ru · 2025-07-21T07:21:08Z

Standards and constraints

URL prefetch/preload only accept boolean true.
Fetch priority accepts only "high" | "low" | "auto".
The as attribute is auto-detected from the filename/extension (image, font, style, script, track, or fallback fetch).
MIME types (e.g., link.type="text/css") are intentionally not set in this PR.

Why numeric order is only for Worker (not URL)

Worker and dynamic import() create async chunks and chunk groups. Webpack can attach prefetchOrder/preloadOrder to these groups and deterministically schedule resource hints after the parent chunk has loaded.
new URL() is a single-asset link injection with no chunk graph ordering semantics. Even if Webpack tried to impose an order, browsers schedule link fetches independently, so numeric values would be misleading and fragile.
Therefore:
- Worker: numeric order is meaningful and matches existing import() semantics.
- URL: boolean-only prefetch/preload for clarity and standards alignment; use fetchpriority for relative urgency instead.

3ru · 2025-08-10T03:31:47Z

rebased

evenstensberg · 2025-10-16T13:14:25Z

Let's try to get this reviewd, patched and merged soon.

… for Worker syntax

…upport for new URL() syntax

…bals.scriptNonce

- Consolidate multiple runtime modules into unified AssetResourcePrefetchPlugin - Remove complex startup prefetch mechanism in favor of simpler inline approach

…PrefetchRuntimeModule`

…Dependency class

- Introduced `preloadAs`, `preloadType`, and `preloadMedia` properties to `URLDependency` for better control over asset preloading.

…Type`, and `webpackPreloadMedia` values.

3ru · 2025-10-30T13:36:01Z

Rebased this on the latest.
@alexander-akait Let me know if you need anything else from my side!

alexander-akait · 2025-10-30T13:49:56Z

@3ru Thanks, a lot of tasks, still in my TODO 😞

Add a single `output.resourceHints` config that controls `<link rel="prefetch">` / `<link rel="preload">` injection for every URL-referenced asset in the bundle. The link is emitted at chunk startup by a small runtime module that runs before any user module in the chunk evaluates — for both initial and async chunks — so the browser already has the response in flight by the time user code references it. Honored from three sources: - JavaScript — `new URL(/* webpackPrefetch: true */ "./img.png", import.meta.url)` and `new Worker(new URL(/* webpackPreload: true */ "./w.js", import.meta.url))`. The hint comment must sit inside the inner `new URL(...)`; comments anywhere else in `new Worker(...)` are ignored. - CSS (`experiments.css`) — `/* webpackPreload: true */ url("./font.woff2")`. - HTML (`experiments.html`) — ` <img src="/asset?url=https%3A%2F%2Fgithub.com%2Fwebpack%2Fwebpack%2Fpull%2Fhero.png">`. Recognized comment keys: `webpackPrefetch`, `webpackPreload`, `webpackFetchPriority`, plus `webpackAs` / `webpackType` / `webpackMedia` on JS `new URL(...)`. The `as` attribute is auto-detected from the file extension when `webpackAs` is omitted. Project-wide defaults via `output.resourceHints` (single rule or array of rules; each rule accepts the standard webpack `test` / `include` / `exclude` matchers): output: { resourceHints: [ { test: /\.(png|jpg|webp)$/, prefetch: true, fetchPriority: "low" }, { test: /\.woff2$/, preload: true, fetchPriority: "high" } ] } Per-call magic comments win over the project-wide default. CSP nonce on the bundle's `<script>` tag is picked up automatically (via `document.currentScript.nonce` for script output, `document.querySelectorAll('script')` matched by `import.meta.url` for `output.module: true`). Plugin authors can extend the generated `<link>` markup via `ResourceHintRuntimeModule.getCompilationHooks(compilation).linkPrefetch` / `.linkPreload`, and new URL emitters can read the same project-wide config via `ResourceHintPlugin.getCompilationResolver(compilation)`. Tests under `test/configCases/asset-modules/url-prefetch-preload*` and `test/configCases/worker/worker-prefetch-preload` cover JS / CSS / HTML sources, single + array config form, ESM output, split-runtime, CSP nonce, and per-call magic-comment overrides. #19695

3ru force-pushed the feature/worker-prefetch-preload-support branch from 329587d to 13027da Compare July 13, 2025 08:02

alexander-akait reviewed Jul 14, 2025

View reviewed changes

Comment thread test/configCases/worker/worker-prefetch-preload/index.js Outdated

alexander-akait reviewed Jul 18, 2025

View reviewed changes

Comment thread test/configCases/worker/worker-prefetch-preload/index.js Outdated

3ru force-pushed the feature/worker-prefetch-preload-support branch from f0ffcb7 to 2bb3de1 Compare July 21, 2025 06:39

3ru changed the title ~~feat: add webpackPrefetch / webpackPreload / webpackFetchPriority support for Worker syntax~~ feat: add webpackPrefetch/webpackPreload/webpackFetchPriority support for URL-based assets Jul 21, 2025

3ru force-pushed the feature/worker-prefetch-preload-support branch from 2bb3de1 to 3cc5c91 Compare July 21, 2025 07:07

xiaoxiaojx reviewed Jul 26, 2025

View reviewed changes

Comment thread lib/dependencies/URLDependency.js Outdated

xiaoxiaojx reviewed Jul 26, 2025

View reviewed changes

Comment thread lib/runtime/AssetPrefetchPreloadRuntimeModule.js Outdated

alexander-akait reviewed Jul 26, 2025

View reviewed changes

Comment thread lib/url/URLParserPlugin.js

alexander-akait reviewed Jul 26, 2025

View reviewed changes

Comment thread lib/url/URLParserPlugin.js

alexander-akait reviewed Jul 26, 2025

View reviewed changes

Comment thread test/configCases/asset-modules/url-prefetch-preload-fetchpriority/index.js Outdated

alexander-akait reviewed Jul 26, 2025

View reviewed changes

Comment thread test/dependencies/URLDependency.unittest.js Outdated

xiaoxiaojx reviewed Jul 26, 2025

View reviewed changes

Comment thread lib/dependencies/URLDependency.js Outdated

3ru force-pushed the feature/worker-prefetch-preload-support branch 4 times, most recently from e059f1b to 9ff7ec7 Compare July 27, 2025 20:50

3ru force-pushed the feature/worker-prefetch-preload-support branch 4 times, most recently from 76d6374 to 270fdeb Compare August 10, 2025 02:50

3ru force-pushed the feature/worker-prefetch-preload-support branch from 270fdeb to a84e769 Compare August 10, 2025 03:47

xiaoxiaojx reviewed Aug 10, 2025

View reviewed changes

Comment thread lib/asset/AssetResourcePrefetchPlugin.js Outdated

xiaoxiaojx reviewed Aug 10, 2025

View reviewed changes

Comment thread lib/asset/AssetResourcePrefetchPlugin.js Outdated

3ru force-pushed the feature/worker-prefetch-preload-support branch from a84e769 to f7283bc Compare August 10, 2025 09:08

xiaoxiaojx reviewed Aug 10, 2025

View reviewed changes

Comment thread lib/dependencies/URLDependency.js Outdated

xiaoxiaojx reviewed Aug 10, 2025

View reviewed changes

Comment thread lib/url/URLParserPlugin.js

3ru added 23 commits October 30, 2025 06:00

feat: add webpackPrefetch/webpackPreload/webpackFetchPriority support…

5a38827

… for Worker syntax

test: update Worker magic comment tests to follow webpack conventions

14a4e85

refactor: move prefetch/preload support from Worker to new URL() syntax

175b856

feat: implement URL-based prefetch/preload support with runtime modules

751f380

feat: implement webpackPrefetch/webpackPreload/webpackFetchPriority s…

3965a55

…upport for new URL() syntax

fix: resolve linting errors in test files

6dcc2c1

refactor: remove prefetch/preload conflict warning and use RuntimeGlo…

4164b5c

…bals.scriptNonce

refactor: extract asset type determination logic into separate function

b1391f3

test: clean up tests and remove outdated functionality

0f946ac

feat: add webpackPreloadType support for new URL() syntax

995677c

fix: move asset prefetch/preload execution from inline to startup time

9319f3d

fix: resolve cache invalidation issues in asset prefetch implementation

af2a2f8

refactor: extract asset type determination logic into util module

ca15705

chore: comments

737acdb

refactor: simplify asset prefetch/preload implementation

baf8e46

- Consolidate multiple runtime modules into unified AssetResourcePrefetchPlugin - Remove complex startup prefetch mechanism in favor of simpler inline approach

fix: only enable URL asset prefetch/preload hints for web targets

9c0420c

refactor: replace AssetResourcePrefetchRuntimeModule with `Resource…

99f67c2

…PrefetchRuntimeModule`

refactor: move asset type determination logic from util module to URL…

c60dbc9

…Dependency class

feat(runtime): improve asset prefetch/preload for universal target

e79d71b

feat: add preload options for enhanced asset loading

46a8081

- Introduced `preloadAs`, `preloadType`, and `preloadMedia` properties to `URLDependency` for better control over asset preloading.

tests: add test cases for invalid webpackPreloadAs, `webpackPreload…

6293ee5

…Type`, and `webpackPreloadMedia` values.

refactor

8d92be8

refactor: simplify webpackPreloadAs validation and update warnings

aaae36e

3ru force-pushed the feature/worker-prefetch-preload-support branch from a8d39c0 to aaae36e Compare October 30, 2025 13:00

Uh oh!

Conversation

3ru commented Jul 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Description

What kind of change does this PR introduce?

Supported magic comments

Example Usage

Did you add tests for your changes?

Does this PR introduce a breaking change?

What needs to be documented once your changes are merged?

Uh oh!

codspeed-hq Bot commented Jul 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #19695 will improve performances by 20.58%

Summary

Benchmarks breakdown

Uh oh!

Uh oh!

Uh oh!

3ru commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Standards and constraints

Why numeric order is only for Worker (not URL)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

3ru commented Aug 10, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

evenstensberg commented Oct 16, 2025

Uh oh!

3ru commented Oct 30, 2025

Uh oh!

alexander-akait commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

3ru commented Jul 13, 2025 •

edited

Loading

codspeed-hq Bot commented Jul 13, 2025 •

edited

Loading

3ru commented Jul 21, 2025 •

edited

Loading