Add a new filter `script_module_data_{$module_id}` to associate data
with a Script Module. For example:
{{{#!php
add_filter(
'script_module_data_MyScriptModuleID',
function ( array $data ): array {
$data['script-needs-this-data'] = 'ok';
return $data;
}
);
}}}
If the Script Module is included in the page, enqueued or as a
dependency, the associated data will be JSON-encoded and embedded in the
HTML in a `<script type="application/json">` tag with an ID of the form
`wp-script-module-data-{$module_id}` allowing the Script Module to
access the data on the client.
See the original proposal: https://make.wordpress.org/core/2024/05/06/proposal-server-to-client-data-sharing-for-script-modules/
Developed in https://github.com/WordPress/wordpress-develop/pull/6682.
Props jonsurrell, cbravobernal, westonruter, gziolo, bernhard-reiter, youknowriad, sergiomdgomes, czapla.
Fixes#61510. See #60647.
Built from https://develop.svn.wordpress.org/trunk@58579
git-svn-id: http://core.svn.wordpress.org/trunk@58026 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Script Modules cannot be used in wp-admin. The necessary hooks are registered on wp_head or wp_footer, but should also be registered for the admin variants so that modules can be used from wp-admin.
Fixes#61086.
Props jonsurrell, cbravobernal, gziolo.
Built from https://develop.svn.wordpress.org/trunk@58126
git-svn-id: http://core.svn.wordpress.org/trunk@57591 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Ensures parity with the `script_loader_src` filter for regular scripts, allowing the URL to be filtered, for example to load them from a CDN or alter query parameters.
Props dd32, peterwilsoncc, westonruter.
Fixes#60742.
Built from https://develop.svn.wordpress.org/trunk@57840
git-svn-id: http://core.svn.wordpress.org/trunk@57341 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Incremental import maps fail if the import map is printed after the module scripts.
This means, we should always render import maps first. This means that for classic themes, we need to move the import map and modules to the footer because we can't know before that which modules are needed.
Props luisherranz, cbravobernal.
Fixes#60240.
Built from https://develop.svn.wordpress.org/trunk@57345
git-svn-id: http://core.svn.wordpress.org/trunk@56851 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Renames all mentions to "module" with "script module", including function names, comments, and tests.
Follow up to [57269]
The list of functions renamed are:
- `wp_module()` -> `wp_script_module()`.
- `wp_register_module()` -> `wp_register_script_module()`.
- `wp_enqueue_module()` -> `wp_enqueue_script_module()`.
- `wp_dequeue_module()` -> `wp_dequeue_script_module()`.
- `WP_Script_Modules::print_enqueued_modules()` -> `WP_Script_Modules::print_enqueued_script_modules()`.
- `WP_Script_Modules::print_module_preloads()` -> `WP_Script_Modules::print_script_module_preloads()`.
It also adds PHP 7 typing to all the functions and improves the types of the `$deps` argument of `wp_register_script_module()` and `wp_enqueue_script_module()` using `@type`.
Props luisherranz, idad5, costdev, nefff, joemcgill, jorbin, swisspidy, jonsurrel, flixos90, gziolo, westonruter, bernhard-reiter, kamranzafar4343
See #56313
Built from https://develop.svn.wordpress.org/trunk@57327
git-svn-id: http://core.svn.wordpress.org/trunk@56833 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This changeset adds a new API for WordPress, designed to work with native ES Modules and Import Maps. It introduces functions such as `wp_register_module`, and `wp_enqueue_module`.
The API aims to provide a familiar experience to the existing `WP_Scripts` class, offering similar functionality. However, **it's not intended to duplicate the exact functionality of `WP_Scripts`**; rather, it is carefully tailored to address the specific needs and capabilities of ES modules.
For this initial version, **the current proposal is intentionally simplistic**, covering only the essential features needed to work with ES modules. Other enhancements and optimizations can be added later as the community identifies additional requirements and use cases.
== Differences Between WP_Script_Modules and WP_Scripts
=== Dependency Specification
With `WP_Script_Modules`, the array of dependencies supports not only strings but also arrays that include the dependency import type (`static` or `dynamic`). This design choice allows for future extensions of dependency properties, such as adding a `version` property to support "scopes" within import maps.
=== Module Identifier
Instead of a handle, `WP_Script_Modules` utilizes the module identifier, aligning with the module identifiers used in JavaScript files and import maps.
=== Deregistration
There is no equivalent of `wp_deregister_script` at this stage.
== API
=== `wp_register_module( $module_identifier, $src, $deps, $version )`
Registers a module.
{{{
// Registers a module with dependencies and versioning.
wp_register_module(
'my-module',
'/path/to/my-module.js',
array( 'static-dependency-1', 'static-dependency-2' ),
'1.2.3'
);
}}}
{{{
// my-module.js
import { ... } from 'static-dependency-1';
import { ... } from 'static-dependency-2';
// ...
}}}
{{{
// Registers a module with a dynamic dependency.
wp_register_module(
'my-module',
'/path/to/my-module.js',
array(
'static-dependency',
array(
'id' => 'dynamic-dependency',
'import' => 'dynamic'
),
)
);
}}}
{{{
// my-module.js
import { ... } from 'static-dependency';
// ...
const dynamicModule = await import('dynamic-dependency');
}}}
=== `wp_enqueue_module( $module_identifier, $src, $deps, $version )`
Enqueues a module. If a source is provided, it will also register the module.
{{{
wp_enqueue_module( 'my-module' );
}}}
=== `wp_dequeue_module( $module_identifier )`
Dequeues a module.
{{{
wp_dequeue_module( 'my-module' );
}}}
== Output
- When modules are enqueued, they are printed within script tags containing `type="module"` attributes.
- Additionally, static dependencies of enqueued modules utilize `link` tags with `rel="modulepreload"` attributes.
- Lastly, an import map is generated and inserted using a `<script type="importmap">` tag.
{{{
<script type="module" src="/path/to/my-module.js" id="my-module"></script>
<link rel="modulepreload" href="/path/to/static-dependency.js" id="static-dependency" />
<script type="importmap">
{
"imports": {
"static-dependency": "/path/to/static-dependency.js",
"dynamic-dependency": "/path/to/dynamic-dependency.js"
}
}
</script>
}}}
== Import Map Polyfill Requirement
Even though all major browsers already support import maps, an import map polyfill is required until the percentage of users using old browser versions without import map support drops significantly.
This work is ongoing and will be added once it's ready. Progress is tracked in #60232.
Props luisherranz, idad5, costdev, neffff, joemcgill, jorbin, swissspidy, jonsurrell, flixos90, gziolo, westonruter.
Fixes#56313.
Built from https://develop.svn.wordpress.org/trunk@57269
git-svn-id: http://core.svn.wordpress.org/trunk@56775 1a063a9b-81f0-0310-95a4-ce76da25c4cd
