WordPress 5.0 adds a number of new bundled script handles, including many specific to the new editor, as well as a few vendor dependencies. Given that a plugin 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 or theme may already have registered their own copies of these same dependencies, this post is meant to serve as a reference for maximum interoperability. These are tips which could apply for any new dependency added by WordPress in any version, but are more likely than usual to be encountered given the amount of new JavaScript 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/. included starting in 5.0.
WordPress-Specific Scripts
All new WordPress-specific JavaScript code is registered using wp-
as a prefix for the script handle. These include the following script handles:
wp-a11y
wp-annotations
wp-api-fetch
wp-autop
wp-blob
wp-block-library
wp-block-serialization-default-parser
wp-blocks
wp-components
wp-compose
wp-core-data
wp-data
wp-date
wp-deprecated
wp-dom-ready
wp-dom
wp-edit-post
wp-editor
wp-element
wp-escape-html
wp-format-library
wp-hooks
wp-html-entities
wp-i18n
wp-is-shallow-equal
wp-keycodes
wp-list-reusable-blocks
wp-notices
wp-nux
wp-plugins
wp-polyfill-element-closest
wp-polyfill-fetch
wp-polyfill-formdata
wp-polyfill-node-contains
wp-polyfill
wp-redux-routine
wp-rich-text
wp-shortcode
wp-token-list
wp-url
wp-viewport
wp-wordcount
Documentation for these packages can be found in the Gutenberg Handbook. They are also available for consumption via npm under the @wordpress
scope (excluding polyfills).
Each WordPress package above assigns itself to the global scope under the wp
namespace. For example, if your theme or plugin enqueues wp-editor
, it will be made available at window.wp.editor
in your browser. Conversely, you should also make sure that, for any JavaScript in your plugin which references a wp
-namespaced library, the associated script handle is defined as a dependency of your script using the third argument of wp_enqueue_script
and wp_register_script
.
Vendor Dependencies
The following vendor dependencies have been added in WordPress 5.0:
For vendor scripts in particular, there is a chance for conflict A conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved. if a plugin or theme registers their own copy of the dependency with the same un-prefixed name. There is a greater likelihood if there is a large version mismatch between the registered scripts.
In general, a plugin should seek to avoid naming collisions by following the best practice of “Prefix Everything” as prescribed in the Plugin Handbook. While this can sometimes result in multiple copies of a script being present in a page, it reduces the chance for breakage and grants WordPress the option to use the unprefixed name in the future.
For dependencies which assign themselves to the global window
scope, wp_add_inline_script
can be used to ensure it is assigned to a global name unique to your plugin or theme. For example, the following snippet demonstrates including React React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. on a page for a plugin without interfering with a core Core is the set of software required to run WordPress. The Core Development Team builds WordPress.-enqueued copy of React, whether or not it exists:
wp_enqueue_script( 'myplugin-react', 'https://unpkg.com/react@16.6.0/umd/react.production.min.js' );
wp_add_inline_script( 'myplugin-react', 'window._originalReact = window.React;', 'before' );
wp_add_inline_script( 'myplugin-react', 'window.mypluginReact = window.React; window.React = window._originalReact;' );
With the above snippet, your intended copy of React will be guaranteed to be available at window.mypluginReact
. This pattern can be applied to any vendor dependency to ensure compatibility with libraries added to WordPress in the future.
If your plugin or theme registers a script with using one of the above script handles as its registered name, consider taking one of the following steps:
Depending on whether you plan to continue support for versions of WordPress earlier than 5.0…
- If you are only intending to target 5.0 and newer, verify compatibility between the versions of the library and simply remove your plugin or theme’s registration of the conflicting script handle.
- If earlier version support is needed, and assuming your script registration occurs after the default scripts are registered (after
wp_default_scripts
), check for whether the script handle is already registered , then register or enqueue your copy of the script, optionally deregistering the core-registered script. Note that since core code targets a specific version of the vendor dependency, deregistering the script may have adverse effects on screens where it is used (notably the new editor screen).- Alternatively, follow the pattern as described above to assign your plugin’s copy of the library to a unique name.
Lodash Global
By default, Lodash will assign itself on the global scope using the _
name. Since WordPress will continue to bundle Underscore for the foreseeable future (see #43733), the core-registered Lodash adopts an approach similar to the enqueuing of jQuery to avoid naming conflicts. It does so using Lodash’s _.noConflict
, assigning Lodash to the global scope as window.lodash
.
For this reason, if your plugin or theme uses Lodash as a dependency, you should make sure to not cause _.noConflict
to be called multiple times in conflict with the core-registered script.
- When using the copy of Lodash registered by core, your code should reference it by the
window.lodash
global. - When enqueuing your own copy of Lodash, you should only call Lodash’s
_.noConflict
under the condition that window.lodash
is not already assigned and that the core-registered Lodash will not be included on the page.
In general, the _
global should be used only to reference Underscore.
React and wp-element
When extending the new editor interface, you should use the new wp-element
script handle, rather than React directly. The element package is a thin abstraction over the React interface, and implements most all of the same functionality. Targeting wp-element
will ensure the greatest compatibility for your plugin as new versions of WordPress are released.
Refer to the wp-element
package documentation and React website for more information.
#5-0, #dev-notes, #javascript