Introduce `fetchpriority` for Scripts and Script Modules #8815

westonruter · 2025-05-19T05:14:29Z

Add new fetchpriority argument to go alongside the loading strategy (async & defer) when registering scripts via wp_register_script()/wp_enqueue_script(). This is a follow-up to the script loading strategies introduced in Core-12009.
Add a new 5th$args parameter to wp_register_script_module()/wp_enqueue_script_module() (and their corresponding methods) to mirror the same 5th $args parameter used in wp_register_script()/wp_enqeue_script(). This $args parameter same fetchpriority argument introduced for non-script modules. (Note that module scripts have a defer loading strategy by default, so adding support for a strategy would only be useful for async. This is not in the scope of this PR.) This will apply the fetchpriority attribute both to the SCRIPT[type="module"] tags as well as the LINK[rel="modulepreload"] tags for static import dependencies.
A new WP_Script_Modules::set_fetchpriority( string $id, string $priority ) method is added which allows the priority of registered scripts to be changed.
The default fetchpriority value for both scripts and script modules is auto.
When the fetchpriority attribute is emitted on SCRIPT and LINK tags, it is omitted if the value is auto since this is the default value.
The comment-reply script is given an explicit fetchpriority of low. While the script is already registered with the async loading strategy which Chrome causes the resource to be downloaded with a low priority by default, this is not the case for Safari or Firefox which use a default medium/normal priority. So the explicit low priority reduces the chance that the loading of the comment-reply script will interfere with the loading of resources needed in the critical rendering path (e.g. an LCP image element).
Script modules used for the view module scripts for blocks with Interactivity API support are given an explicit fetchpriority of low. The very first requirement/goal defined for the Interactivity API was for server-side rendering, therefore blocks should not depend on the view module script for initial rendering.
Tests have been written for the changes both to scripts and script modules, but the tests for the latter have additional changes since deficiencies were discovered (e.g. duplicate array keys, and global functions were untested).

Note

If Gutenberg is active, you won't see any changes without WordPress/gutenberg#70173 also checked out.

Trac ticket: https://core.trac.wordpress.org/ticket/61734

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2025-05-19T05:26:54Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

…odules

swissspidy · 2025-05-20T15:54:37Z

src/wp-includes/blocks.php

@@ -175,11 +175,18 @@ function register_block_script_module_id( $metadata, $field_name, $index = 0 ) {
 	$block_version       = isset( $metadata['version'] ) ? $metadata['version'] : false;
 	$module_version      = isset( $module_asset['version'] ) ? $module_asset['version'] : $block_version;

+	$args = array();
+	if ( isset( $metadata['supports']['interactivity'] ) && $metadata['supports']['interactivity'] ) {
+		// TODO: Add ability for the fetchpriority to be specified in block.json for the viewScriptModule. In wp_default_script_modules() the fetchpriority defaults to low since server-side rendering is employed for core blocks, but there are no guarantees that this is the case for non-core blocks. That said, viewScriptModule entails Interactivity API, following the pattern from core it _should_ be SSR'ed and that is why this is the default for when the block supports interactivity.


Maybe that property in block.json should become an object instead of a string. In the future we might need other properties in there too.

cc @gziolo

Absolutely! See below 😄 #8815 (comment)

I think this would make sense as a future enhancement, that this doesn't need to be implemented in this PR. If the low fetch priority is wrong, it could be fixed with a call to the new WP_Scripts_Modules::set_fetchpriority().

swissspidy · 2025-05-20T15:55:09Z

src/wp-includes/blocks.php

@@ -243,6 +250,7 @@ function register_block_script_handle( $metadata, $field_name, $index = 0 ) {
 	$script_args         = array();
 	if ( 'viewScript' === $field_name && $script_uri ) {
 		$script_args['strategy'] = 'defer';
+		// TODO: There needs to be a way to specify that a script defined in a module is safe to use fetchpriority=low. Perhaps the viewScript should not only allow a handle string or a `file:./foo.js` string, but allow an an array of params like { "href": "./foo.js", "fetchpriority": "low" }. This would allow for more metadata to be supplied, like the script loading strategy. Related: <https://core.trac.wordpress.org/ticket/56408> and <https://core.trac.wordpress.org/ticket/54018>.


Oh, yes, exactly what I meant above 😅

src/wp-includes/script-modules.php

src/wp-includes/class-wp-script-modules.php

Co-authored-by: Pascal Birchler <[email protected]>

src/wp-includes/blocks.php

Co-authored-by: Luis Herranz <[email protected]>

westonruter · 2025-05-21T15:27:19Z

src/wp-includes/class-wp-script-modules.php

+ * @phpstan-type ScriptModule array{
+ *     src: string,
+ *     version: string|false|null,
+ *     enqueue: bool,
+ *     dependencies: array<array{ id: string, import: 'dynamic'|'static' }>,
+ *     fetchpriority: 'auto'|'low'|'high',
+ * }


I added these @phpstan annotations for myself as a safeguard while developing this patch. If others don't want PHPStan annotations in core, I'll remove prior to commit.

For better consistency, I think it's better to remove these annotations prior to commit indeed, as this is not something used elsewhere in Core. Also I dunno how the docblock parser will handle these info but I think it's going to add a lot of noise in dockblocks displayed on the generated documentation (same goes for other related phpstan annotations)

Removed in 74a49e1

github-actions · 2025-05-26T21:09:08Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter, swissspidy, luisherranz, kraftbj, audrasjb.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

kraftbj

I tested this for regular scripts and it worked as advertised. I did confirm that add_data checks for is_scalar down the chain so lack of type checking here isn't an issue. The Web API, per MDN, will default to auto if not present or if the value is not valid (low, high, auto).

audrasjb

left a comment about phpstan docblock annotations

audrasjb · 2025-06-19T15:18:13Z

src/wp-includes/class-wp-script-modules.php

+ * @phpstan-type ScriptModule array{
+ *     src: string,
+ *     version: string|false|null,
+ *     enqueue: bool,
+ *     dependencies: array<array{ id: string, import: 'dynamic'|'static' }>,
+ *     fetchpriority: 'auto'|'low'|'high',
+ * }


For better consistency, I think it's better to remove these annotations prior to commit indeed, as this is not something used elsewhere in Core. Also I dunno how the docblock parser will handle these info but I think it's going to add a lot of noise in dockblocks displayed on the generated documentation (same goes for other related phpstan annotations)

audrasjb · 2025-06-19T15:20:14Z

@westonruter if this is still on track for 6.8.2, note that the PR is conflicting against trunk ;)

…into trac-61734 * 'trunk' of https://github.com/WordPress/wordpress-develop: (88 commits) Docs: Correct parameter and return types for some comment functions. Database: Reinstate test for MariaDB version in readme. Coding Standards: Remove unreachable `return` in `_get_block_template_file()`. Build/Test Tools: Fix playground workflow link in PR comment. Build/Test Tools: Revert [60324] while memory exhaustion issues in the GitHub Actions workflows are investigated. Docs: Remove redundant `@access` tags from DocBlocks in various files. Build/Test Tools: Bump the default baseline version used for performance comparison tests. Build/Test Tools: Update the currently supported branch that's used to determine the frequency of scheduled tests of old branches. Build/Test Tools: Update the upgrade testing matrix to reflect `6.8`. Build/Test Tools: Finalise changes to the WordPress versions used during upgrade testing from the development branch. Security: Update `composer/ca-bundle` to version 1.5.7. Site Health: Bump the recommended version of MariaDB to `10.6`. Build/Test Tools: Add inline docs to explain the PHPUnit strategy. do_blocks(): Free up transient memory leak Build/Test Tools: Switch to the GraphQL API for searching pull requests. Build/Test Tools: Use `issues` instead of `issuesAndPullRequests`. Database: Temporarily skip the `test_readme_mariadb_version` test method. Docs: Add missing DocBlock for the `_()` function in `compat.php`. Docs: Correct property type for `WP_Tax_Query::$no_results`. Coding Standards: Remove extra check in `wp_authenticate_application_password()`. ...

westonruter · 2025-06-20T23:40:43Z

if this is still on track for 6.8.2, note that the PR is conflicting against trunk ;)

@audrasjb Merge conflicts resolved in 4197eb2

westonruter added 3 commits May 18, 2025 20:10

Output script modules with fetchpriority=low

dbcd32c

Fix duplicate array keys in data_special_chars_script_encoding

5207c27

Add ability to set fetch priority for script modules

088366d

westonruter added 8 commits May 19, 2025 12:26

Add fetchpriority support for non-module scripts

9eab85d

Set fetchpriority=low on comment-reply script

d9c4037

Use auto as default fetchpriority for script modules

4f82a4f

Avoid printing fetchpriority attribute when auto

f2cd9be

fixup! Use auto as default fetchpriority for script modules

ff4fd36

Use HTML Tag Processor to parse import map

9edbe4c

Ensure parity in args between class methods and global function aliases

021fe74

Use fetch priority low by default for Interactivity API view script m…

34ef7fa

…odules

westonruter changed the title ~~Use fetchpriority=low by default for script modules and add ability to override~~ Introduce fetchpriority for Scripts and Script Modules May 20, 2025

swissspidy reviewed May 20, 2025

View reviewed changes

src/wp-includes/script-modules.php Show resolved Hide resolved

swissspidy reviewed May 20, 2025

View reviewed changes

src/wp-includes/script-modules.php Show resolved Hide resolved

swissspidy reviewed May 20, 2025

View reviewed changes

src/wp-includes/class-wp-script-modules.php Show resolved Hide resolved

Add missing since tag

e54274a

Co-authored-by: Pascal Birchler <[email protected]>

westonruter mentioned this pull request May 21, 2025

Add fetchpriority=low support to script modules WordPress/gutenberg#70173

Draft

luisherranz reviewed May 21, 2025

View reviewed changes

src/wp-includes/blocks.php Outdated Show resolved Hide resolved

Account for full block.json schema when checking for interactivity

cc1d909

Co-authored-by: Luis Herranz <[email protected]>

westonruter commented May 21, 2025

View reviewed changes

westonruter marked this pull request as ready for review May 26, 2025 21:08

kraftbj approved these changes Jun 5, 2025

View reviewed changes

kraftbj mentioned this pull request Jun 5, 2025

Enhancement: Improve performance by deprioritizing Stats script Automattic/jetpack#43631

Open

westonruter requested a review from felixarntz June 9, 2025 15:17

audrasjb reviewed Jun 19, 2025

View reviewed changes

westonruter added 2 commits June 20, 2025 16:35

Remove PHPStan annotations for commit

74a49e1

westonruter requested review from azaozz and joemcgill June 21, 2025 17:28

Introduce fetchpriority for Scripts and Script Modules #8815

Are you sure you want to change the base?

Introduce fetchpriority for Scripts and Script Modules #8815

Conversation

westonruter commented May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented May 19, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kraftbj left a comment

Choose a reason for hiding this comment

Uh oh!

audrasjb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

audrasjb commented Jun 19, 2025

Uh oh!

westonruter commented Jun 20, 2025

Uh oh!

Uh oh!

Introduce `fetchpriority` for Scripts and Script Modules #8815

Introduce `fetchpriority` for Scripts and Script Modules #8815

westonruter commented May 19, 2025 •

edited

Loading

github-actions bot commented May 26, 2025 •

edited

Loading