WordPress.org

Welcome!

The WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:

Found a bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.? Create a ticket in the bug tracker.

Want to contribute? Get started quickly with tickets marked as good first bugs for new contributors or join a bug scrub. There’s more on the reports page, like patches needing testing, and on feature projects page.

Other questions? Here is a detailed handbook for contributors, complete with tutorials.

A new “Script Modules” interface has been introduced to support native JavaScript modules in WordPress. JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. modules use import and export and are often referred to as ECMAScript Modules or “ESM”.

This post will refer to “scripts” and “modules” for Scripts and Script Modules concepts, respectively.

JavaScript modules are a coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. web technology with a number of benefits like import and export for proper scoping, forced strict mode, and deferred loading. It’s important for WordPress to support modules and encourage their use as the future of JavaScript development.

Script Modules APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.

The interface is modeled after the existing scripts interface and should feel familiar. Modules are identified by a unique identifier (ID), analogous to a script handle.

The registered module ID should be identical to the imported module name in JavaScript. For example, the @wordpress/interactivity module can be used in another module as:

import * as interactivity from '@wordpress/interactivity';

Registered modules have an array of module dependencies. Dependencies can be a simple string (the dependency module ID) or an associative array of the following form:

$dependencies = array(
	'id' => '@wordpress/interactivity',
	'import' => 'dynamic' // Optional.
);

The array form optionally includes an import key with the value 'static' (default) or 'dynamic'. Dependencies that may not be needed or should only be loaded under some circumstances should use 'import' => 'dynamic'.

Note that these dependencies are module dependencies, not script dependencies. Script handles should not be listed as module dependencies.

The following functions are the most relevant parts of the interface for developers working with modules:

wp_register_script_module( string $id, string $src, array $deps = array(), $version = false ): Registers the module.
wp_enqueue_script_module( string $id, string $src = '', array $deps = array(), $version = false ): Marks the module to be enqueued. An optional $src argument can be provided to enqueue and register the module.
wp_deregister_script_module( string $id ): Deregisters the module.
wp_dequeue_script_module( string $id ): Unmarks the module so it is not enqueued.

Important notes

It’s strongly recommended that developers currently utilizing JavaScript modules in their extensions migrate to the Script Modules API. This will standardize behavior, bring a number of benefits, and prevent some of the following potential issues:

Any code that is currently using import maps may run into compatibility issues because multiple import maps are not currently supported.
If a module appears before an import map, an error will be triggered that causes the import map to be ignored. This would break some critical functionality that the Script Modules API relies on.

It’s important to migrate to the new API to prevent these issues. If it’s unfeasible to migrate, moving modules script to the footer may mitigate some of the potential issues.

Available modules

Two core modules are provided with 6.5.

@wordpress/interactivity is the interface for building interactive frontends with the Interactivity API.

@wordpress/interactivity-router defines an Interactivity API store with the core/router namespace, exposing relevant state and actions for client-side navigation.

There are no other core modules available at this time. The JavaScript packages available as scripts before 6.5 are not available as modules. For example, the @wordpress/api-fetch package corresponds to the wp-api-fetch script and is not available in WordPress as a module.

Working with Script Modules

The most relevant functions for working with modules are wp_register_script_module to register and wp_enqueue_script_module to enqueue modules. For example:

// Registers a module, it can now appear as a dependency or be enqueued.
wp_register_script_module(
	'@my-plugin/shared',
	plugin_dir_url( __FILE__ ) . 'shared.js'
);

// Registers and enqueues a module.
wp_enqueue_script_module(
	'@my-plugin/entry',
	plugin_dir_url( __FILE__ ) . 'entry.js',
	array( '@my-plugin/shared' )
);

// Enqueues a previously registered module.
wp_enqueue_script_module( '@my-plugin/a-registered-module' );

In this example, the @my-plugin/shared module will be available to the @my-plugin/entry module:

// "@my-plugin/entry" module at …/entry.js
import * as shared from '@my-plugin/shared';
shared.doSomethingInteresting();

Blocks

WordPress 6.5 introduces a new viewScriptModule block metadata field that will handle module registration and enqueue automatically analogous to viewScript. A full dev note about viewScriptModule can be read here.

Module registration

Developers familiar with modern JavaScript development will recognize the module system and may wonder, “Do I have to register all my modules with WordPress in order to use them?” The short answer is no, but the recommended approach is to register all the modules.

JavaScript modules can import be imported by URLs. It’s common to see imports like import { utility } from './utilities.js' in modern applications. Because the Script Modules API is built on top of native JavaScript modules, it’s possible for modules to import relative paths in WordPress. However, the recommended approach is to register modules and use the registered ID to import the module. This has a few benefits:

Registered modules are available globally. There’s no need to worry about the module URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org.
Registered modules have versions. The Script Modules API transparently handles associating a module ID with the correct URL and version.
Risk of module duplication is reduced. If a module is imported through different URLs, the browser may fetch and execute multiple copies of what is ostensibly the same module.
Dependencies that are imported statically will be preloaded when the module is enqueued. This allows the browser to fetch them in parallel.

Relative imports to unregistered modules may be useful for prototyping and exploration, but the best practice for production code is to register modules with the Script Modules API.

Limitations

Modules and scripts are not compatible at this time. Modules cannot depend on scripts and scripts cannot depend on modules. This means that modules cannot depend on scripts like wp-i18n, wp-api-fetch, etc.

There is a workaround to use scripts from modules. Script functionality is shared by adding variables to the window scope, for example wp-api-fetch can be accessed via window.wp.apiFetch. To use scripts from modules at this time, developers must:

Ensure that the script is enqueued: wp_enqueue_script( ‘wp-api-fetch’ )
Access the script through the global scope: const { apiFetch } = window.wp

There are a number of downsides to this workaround, but it can be an effective solution. Follow Core Trac ticket #60647 for work on script and module interoperability.

Compatibility

JavaScript modules have excellent support in most browsers today. In addition, the Script Modules API includes a polyfill for browsers with lacking or incomplete support to make the number of supported browsers even greater.

Technical details

A full explanation of how the Script Modules API works is beyond the scope of this note, but this section will provide a brief overview.

The Script Modules API will track registered and enqueued modules. For each enqueued module, a <script type="module"> tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) will be added to load and execute the module.

A <script type="importmap"> tag will be added. The import map tells the browser how to map module IDs to URLs so that when it sees an import for '@wordpress/interactivity', it knows that the module should be fetched from the URL /wp-includes/js/dist/interactivity.min.js?ver=xyz. The import map includes all the dependencies of all enqueued modules, and all the dependencies of those dependencies, etc. The import map will not include dependencies of all the registered modules, only those that may be required on the page as dependencies, and it will not include the enqueued modules unless they are in the dependency graph of other enqueued modules.

A <link rel="modulepreload"> will be added for all static dependencies. Static dependencies are all dependencies that are not defined as array( 'id' => '…', 'import' => 'dynamic' ). This is an optimization hint for browsers, read more about it here.

Relevant links

Props

@cbravobernal for technical review.
@gziolo for technical review.
@bernhard-reiter for technical review.
@leonnugraha for copy review.
@stevenlinx for copy review.

#6-5, #dev-notes, #dev-notes-6-5

stevygee1987 4:21 pm on March 26, 2024

Is there a way to localize script modules, like we do for regular scripts using wp_localize_script()?
- Greg Ziółkowski 9:28 am on March 27, 2024
  
  It isn’t supported yet, but a related TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. is open, and you can follow progress at https://core.trac.wordpress.org/ticket/60234. It’s a more challenging task than with regular script because modules can be loaded dynamically, so a mechanism that can account for that needs to be created. In addition to that, there is no interoperability layer between regular scripts and ES Modules, so `wp-i18ni18n Internationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see localization. Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill.` can’t be used as is.
Tomek 9:14 pm on March 27, 2024
How can I use the new APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. to create inline modules?

I need to pass some inline data to my module, so I’d like to use the API to create achieve something like:
```
<script type="module" src=".../plugins/my-plugin.js" id="my-plugin-js-module"></script>
<script type="module>
import doMagic from 'my-plugin';
doMagic( inlinedJSON );
</script>
```
- Jon Surrell 4:06 pm on April 2, 2024
  
  There’s nothing analogous to wp_add_inline_script for modules at this time.
  One difficulty is that often modules will not have an associated script tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.). Modules may appear in the importmap but never be loaded at all! In this case, there’s no obvious place where to put the associated inline module. Even if there is a script tag, it may be difficult to ensure that the initialization happens before the module is used by another module.
  The best solution at this time may be to enqueue your module and add a script tag with type="module" that contains the initialization using something like wp_print_inline_script_tag.
  It may be worth creating a TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. to discuss this in detail.
Tomek 9:26 pm on March 27, 2024

Also, do you plan to add classic script dependencies to modules?

I’d like to migrate by pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party’s code to ES Modules, but unfortunately, it has some external dependencies, which expect to be loaded as classic scripts.
- Greg Ziółkowski 12:18 pm on March 28, 2024
  
  See the Limitations section in the post. There is Core Trac ticket #60647 for work on script and module interoperability.
mikeill 9:32 pm on April 16, 2024
Should I expect this feature, at this time, to work with `wp_localize_script`? It doesn’t seem to. As noted here in https://wordpress.stackexchange.com/a/424530/48604
```
global $wp_scripts
```
, (within a wp_enqueue_scripts action) as far as I’m seeing, the handle string registered via wp_register_script_module isn’t present.
- Jon Surrell 6:56 am on April 23, 2024
  
  Scripts and Script Modules are separate systems. `wp_localize_script` will not work with Script Modules, and registered Script Modules are not expected to appear in the registered Scripts.
  
  Script Modules are missing some features, functionality analogous to `wp_localize_script` may be one of them. There will be work in upcoming releases to improve the experience of working with Script Modules.
mmcgowan1 10:17 pm on April 16, 2024

Once a module is registered, there doesn’t seem to be any way to pass it PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher constants or variables from the backend. None of the standard methods used with common JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. scripts seem to work. Am I missing something?
- Jon Surrell 7:07 am on April 23, 2024
  
  At this time, Script Modules do not have functionality analogous to `wp_add_inline_script` or `wp_localize_script`, which are often used to pass data from the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher to Scripts.
  
  Several CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Scripts, such as `wp-api-fetch`, rely on this functionality. There’s ongoing work to bring some Scripts functionality to Script Modules, so providing a way to pass data to Script Modules may be essential for that work.
Akah Martono 2:44 am on May 28, 2024

Is this only applied to the front end? I tried in the wp-adminadmin (and super admin) didn’t work
- Jon Surrell 7:19 am on May 28, 2024
  
  In WordPress 6.5, the necessary hooks were not registered to be used from WP Admin. That has been fixed and in WordPress 6.6 Script Modules will be available in WP Adminadmin (and super admin).
itumulak 10:33 am on June 3, 2024

For those who run into an issue with the script module and are not able to utilize localization, I have my own Script module class so that you can use JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. modules with localization. It is not perfect but it gets things done.

Check out the Script module here.