Handling potential jQuery issues in WordPress 5.6

WordPress 5.5 stopped enabling the jQuery Migrate helper script by default, and with the upcoming release of WordPress 5.6, the bundled version of jQuery will be upgraded (from 1.12.4-wp to 3.5.1).

What this involves for users, is that any 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 or theme that previously relied on the jQuery Migrate tool to work as expected (due to being older code, or just a missed update to deprecated functions), may now have unexpected behaviors.

In the best of cases, this related to events not being triggered, this just means that some functionality may stop working behind the scenes, no major impact.
The potential issue is the use of function that were deprecated, these will now cause a fatal error, and prevent further pieces of 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/. on your site from working as expected.

The 5.5 solution

For the release of WordPress 5.5, a plugin called Enable jQuery Migrate Helper was created, which would re-enable the jQuery Migrate tool on the site in question, and also make sure that the features making it a necessity were surfaced so the site users would know what is happening.

The initial plan for this plugin was to be a temporary stop-gap to allow plugin and theme authors a little bit more time to update, if they were caught off-guard by the changes in the 5.5 release.

Unfortunately, we can still see many plugins and themes (at time of publishing, before WordPress 5.6 has been released) relying on older code, and we are unaware of the potential impact of paid plugins or themes from across the ecosystem.

The 5.6 solution

With the above in mind, the Enable jQuery Migrate Helper plugin was updated for the release of WordPress 5.6, this provides a temporary downgrade path to run legacy jQuery on a site when needed.

The reason this is considered a temporary solution, is that the older version of jQuery no longer receives security updates, and the legacy version will not be patched manually if anything should occur that warrants updates to it.

The plugin presentation

The plugin provides features and tools aimed at transitioning a site between jQuery versions, either via plugin and theme authors updating their code, or giving a site owner time to find replacements.

Deprecation logging

To find the actual problems on your site, whenever you browser around with the plugin active, it will track any deprecations that are discovered.

Deprecations are warnings relating to outdated code that is being used, but has been made available for a short period of time during your transition. Any feature that is marked as deprecated should be replaced with modern code as soon as possible, to ensure nothing breaks.

The admin bar showing deprecation alerts

The first place you will encounter a deprecation-notice is within the admin bar, found on the top of all sites when you are logged into the backend, but also enabled in the frontend on many sites.

It will show you a count of any issues found on the current page, if it is the front-end, it will be logged to a separate page, dedicated to listing and educating about the warnings that were encountered, in the backend they may be shown instantly on screen, or also get logged, depending on your settings.

Admin menu showing a count of logged deprecations

If there are deprecations previously logged, they may also show an indicator of how many items have been logged in the admin bar, as seen in the provided screenshot, these will remain marked until you clear out the logs.

Deprecation logs, with example pluigins

The deprecation log page it self provides a visual representation of warnings often hidden away and intended for developers within the JavaScript console.

It will provide an easy link to a plugin or themes own website, or their authors site if no other link was available. This kind of direct access will hopefully help users reach out and get updated versions of their code in a more timely fashion than needing to find it based on a slug (a shortname used to reference plugins and themes).

Using legacy jQuery

The setting screen, offering options for changing jQuery versions

The settings screen offers the user the3 choice between using the legacy jQuery (with the tradeoff being an admin notice on every page alerting them to the scenario, and why they should be looking to remedy the need for it as soon as possible), and also a way to enable public deprecation logging.

Public logging may incur an added strain on your server, as any visitor who visits a page leading to an error will send a logging request automatically for the user to go over at their convenience.

Automatic version changes

The target audience are non-technical users, as such they may be unaware of the potential issues the plugin addresses when they upgrade WordPress, or maybe a support person told them to use it to resolve an issue.

In light of this, the first time a site visitor encounters an error caused by a now broken jQuery implementation, the plugin will facilitate an automated downgrade to a legacy jQuery version, and sends an email to the site administrator informing them of what has happened.

This automatic downgrade is a one-time event, changing versions after this will not make it trigger again in the future.

Automated emails, keeping you in the loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop.

Example email sent when using a legacy jQuery version

Once per week, an email is scheduled to be sent out, letting the site administrator know the current state of their site. This email includes information about the plugin and which jQuery issues have been logged in the past week.

This will hopefully ensure site administrators get more involved in resolving problems with their own page.

The email will also encourage the removal of the jQuery Migrate helper plugin, if there have been no registered deprecations within the past week. This will help give a clearer indication of the underlying issue of outdated jQuery instances, by watching the amount of active plugin users.