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 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 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:

• lodash (4.17.11)
• moment (2.22.2)
• react (16.6.3)
• react-dom (16.6.3)

For vendor scripts in particular, there is a chance for conflict 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 on a page for a plugin without interfering with a core-enqueued copy of React, whether or not it exists:

wp_enqueue_script( 'myplugin-react', 'https://unpkg.com/[email protected]/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