View Categories

How to Fix WordPress 5.5 jQuery Conflict

wordpress 5.5 fix
  • Oct 13, 2020
  • 0
  • by A2 Support Team

Updating to the latest and greatest version of WordPress is essential for protecting your website against hackers. However, some updates can cause problems with third-party plugins and themes – which is exactly the case with the recent WordPress 5.5 update.

A jQuery conflict in WordPress 5.5 has the potential to break around 2,400 WordPress plugins and around 250 themes. Thankfully, you don’t have to choose between security, and continuing to use your favorite themes and plugins.

If you’re experiencing issues after upgrading to WordPress 5.5, we’ll show you how to test whether jQuery is to blame. We’ll then sharing four ways to resolve this issue in WordPress. We have lots to cover, so let’s get started!

Why WordPress 5.5 Is Breaking Some Themes and Plugins

Prior to the 5.5 release, WordPress bundled in version 1.12.4 of the jQuery JavaScript library. This version was released in 2016 – just to put things into perspective, this version of jQuery supported Internet Explorer 6, 7, and 8.

As such, the WordPress team has recently started the process of upgrading the version of jQuery that’s bundled with WordPress. When you upgrade to WordPress 5.5, the jQuery Migrate tool is no longer enabled by default.

Unfortunately, this transition hasn’t been straightforward, as some WordPress themes and plugins still rely on older jQuery scripts. For themes and plugins that run older code, this change can cause unexpected behaviors. The WordPress community has even reported issues with popular plugins such as the Classic Editor.

Even if a theme is compatible with WordPress 5.5, there’s a chance it may still encounter issues if it features a plugin that runs outdated code. For example, many premium themes are bundled with page builder plugins. Even if the theme itself doesn’t require jQuery Migrate, users may still encounter problems if the bundled page builder does require this feature.

It’s estimated that around 250 themes are directly affected by this jQuery Migrate update. However, bundled plugins could be causing problems with far more WordPress themes.

Why WordPress Addressed the jQuery Problem Now

jQuery has been a contentious issue in the WordPress community. The decision to disable jQuery Migrate is the culmination of a ticket that WordPress core committer Aaron Jorbin created four years ago. In this ticket, he proposed migrating WordPress to the jQuery 3.x branch.

This jQuery migration issue has forced contributors, developers, and WordPress users to balance security and backwards compatibility. Updating to the latest version of jQuery would help close security loopholes and protect WordPress sites against hackers. However, many themes and plugins rely on older versions of jQuery.

jQuery is also included on the frontend of many websites, particularly websites that support older versions of Internet Explorer. To maintain backwards compatibility with these older browsers, WordPress couldn’t simply switch to the latest version of jQuery overnight.

A patch containing a more recent version of jQuery and jQuery Migrate was created back in 2018. However, this potential update caused issues with WordPress core, particularly the Customizer menus. There was also some debate as to whether WordPress should switch to Vanilla JS for WordPress core, and give developers the option to load jQuery 3.0 if required.

Eventually, it was decided to remove jQuery Migrate 1.x in WordPress 5.5. This would give plugin and theme developers, and website owners some time to prepare for the eventual migration. However, it was generally accepted that some issues were inevitable.

“No matter how we approach this, it will cause ripples,” wrote WordPress core contributor Marius. “jQuery has been in core for so long that it really is a matter of ripping the bandaid off, as they say, or never updating and committing to that.”

After four years of debate, the WordPress contributors decided that the least disruptive course of action would be a three-step approach. This approach started by removing jQuery Migrate 1.x in WordPress 5.5.

How WordPress Has Responded to the Issue

Ahead of the 5.5 release, the WordPress team discussed identifying all the plugins and themes that would be adversely affected by the jQuery migration. They could then contact these developers directly and warn them about the upcoming changes. However, core contributor Gal Baras pointed out that not all WordPress plugin and theme developers host their projects in the official WordPress repository.

“Despite the wide variety of plugins and themes in the repository, let’s keep in mind those available from other sources, the authors of which may not be contactable by email like wp.org authors. Specifically for themes, I’d say that’s the majority of sites out there,” Gal said.

The decision to remove jQuery Migrate 1.x was announced in June over at Make WordPress Core. In an effort to prepare the community, the WordPress team also shared links to some useful resources. These resources included a jQuery Core 3.0 Upgrade Guide and 3.5 Upgrade Guide.

Since the release, WordPress core contributors have been actively engaging with the community. This included requesting feedback regarding their approach to updating jQuery. They have also openly discussed whether the team should progress with the jQuery migration as planned, or take things more slowly. At the time of writing, the consensus was that a decision should be made further down the line.

WordPress has also released 5.5.1, which addressed some of the jQuery issues the community was experiencing. In particular, WordPress 5.5.1 introduced a fix for variables that weren’t getting localized.

WordPress 5.5’s JavaScript Execution Error

In addition to the jQuery conflict, in WordPress 5.5 some JavaScript objects were removed without being deprecated. In WordPress 5.5, referencing any of the following objects will halt JavaScript execution:

  • adminCommentsL10n
    attachMediaBoxL10n
    authcheckL10n
    commentL10n
    commonL10n
    inlineEditL10n
    navMenuL10n
    postL10n
    plugininstallL10n
    privacyToolsL10n
    setPostThumbnailL10n
    tagsl10n
    tagsSuggestL10n
    userProfileL10n
    wp.themePluginEditor.l10n
    wp.updates.l10n
    wpColorPickerL10n
    wpPointerL10n
    wpWidgets.l10n

Yoast founder Joost de Valk and Yoast Chief Technology Officer (CTO) Omar Reiss have created a Google Sheet detailing the impact these objects will have on the various themes and plugins. However, WordPress 5.5.1 added a ‘backfill’ for the affected globals that prevented further JavaScript errors. If your site relies on an affected theme or plugin, you should update to 5.5.1 as soon as possible.

By redeclaring these globals in 5.5.1, WordPress has given theme and plugin developers more time to update their software. However, WordPress currently plans to remove this fallback code in WordPress 5.7, so it’s only a temporary fix.

How to Diagnose JavaScript Errors

If you’re encountering strange behavior after updating to WordPress 5.5, you can check whether the issue is related to a jQuery conflict, using a toolkit such as Chrome DevTools. While our example below uses Google Chrome, the same functionality is found in all major browsers.

You can access the Console by clicking the three-dotted menu icon in Chrome’s upper-right corner. Next, select More Tools > Developer Tools.

The Chrome DevTools menu.

If the Console doesn’t open automatically, you should select the Console tab. Alternatively, you can jump straight into the Console panel, using the Command+Option+J keyboard shortcut on macOS, and Control+Shift+J on Windows and Linux.

If the Console doesn’t display an error, try reloading the page – some errors are only generated when the page loads.

If the Console does display an error, you can view more information by selecting the error’s accompanying link. The console should display the error type, the location of the error, and the line number.

The Error Console in Google Chrome.

If you encounter an Uncaught ReferenceError message, select it – this should launch a new screen containing an error message. To learn more about this error, click its accompanying red X icon.

By carefully reviewing all the information, you should be able to diagnose what’s causing the error. If you’re unsure about a particular error, you could try entering the error text into a search engine. Alternatively, you can post the full error message to a tech-focused question and answer site, such as Stack Overflow.

As we mentioned, you can also check for errors using the Firefox Web Console or Microsoft Edge DevTools. However, if you’re using Safari, you’ll need to enable the Developer Tools before you can troubleshoot your WordPress installation.

In the Safari toolbar, select Safari > Preferences > Advanced, then select Show Develop menu in the menu bar. You can now open the page where you’re encountering the issue, and select Develop > Show Error Console in the Safari toolbar.

4 Ways to Resolve a jQuery Conflict

If you’ve verified that a jQuery conflict is causing issues with your website, there are steps you can take to resolve these issues. Let’s run through them now.

1. Update All Your Themes and Plugins

Since the release of WordPress 5.5, theme and plugin developers have been hard at work updating their software. If you’re running an outdated theme or plugin, you may actually be encountering an issue that’s already been fixed.

To check for available updates, log into your WordPress dashboard and select Updates. From here, you can (of course) update all your themes and plugins.

If you’ve installed one or more updates, check whether this has resolved your problem. Our advice is to try to replicate the original issue, or if you know how to look for it, troubleshoot your site using a toolkit such as Chrome DevTools.

2. Contact the Developer

If you’ve installed the latest update and are still encountering issues, contacting the theme or plugin’s developer is a good idea. It’s possible the developer is unaware of the jQuery conflict, or may be planning to release an update.

If you downloaded the theme or plugin from the official WordPress Plugin Directory, then you should check the plugin’s listing. These listings often include information about websites, forums, or social media profiles where you can contact the team behind the plugin or theme in question. Sometimes, these listings may even contain the developer’s direct contact details.

Alternatively, some developers choose to include their contact information at the code level. If you downloaded the theme or plugin to your computer, try unzipping the folder and searching for a file that contains the developer’s details. The README file is usually a good place to start. These files often contain the names of the core contributors, or the process for contacting support.

When contacting the developer about the issues you’re experiencing, you should include as much information as possible. If you explored the error using a toolkit such as Chrome DevTools, sharing this data with the plugin or theme’s developer is a good idea.

3. Check Whether the Plugin or Theme Is No Longer Maintained

Many plugins and themes are passion projects, rather than commercial ventures. When a project is spearheaded by a very small team or single developer, there’s always a chance that the project loses momentum and stops being maintained, or even abandoned.

The official WordPress Plugin Directory displays the date when each theme and plugin was last updated. Different types of software require more frequent updates than others. However, if a plugin or theme hasn’t been updated within six months, you should approach with caution.

The Yoast SEO plugin, in the official WordPress repository.

If a plugin or theme has a website or social media presence, you can also check these for recent activity. Recent Tweets or a regularly-updated blog suggests that the theme or plugin is still under active development.

If you suspect the theme or plugin is abandoned or otherwise no longer maintained, the solution is to find one that is being actively developed. Almost all WordPress vulnerabilities are related to plugins, so it’s always a good idea to replace unmaintained themes and plugins, regardless of jQuery conflicts.

4. Use the jQuery Migrate Plugin

The Enable jQuery Migrate Helper plugin.
If you’re experiencing jQuery conflicts relating to the 5.5 update, WordPress has its own temporary solution – the Enable jQuery Migrate Helper plugin. If you need to continue using a plugin or theme that’s causing jQuery conflicts, this plugin provides a backwards-compatible fix.

It essentially re-enables the migration script for your website, and gives the theme or plugin’s developer some extra time to update their software.

While, the Enable jQuery helper plugin is designed to run in production – i.e. on a live site – it doesn’t fix what’s broken by the WordPress 5.5 update. As such, you should treat this plugin as a temporary fix, rather than a permanent solution.

Preparing for WordPress 5.6 and Beyond

Disabling jQuery Migrate is the first step in WordPress’ three-step plans for jQuery. According to Andrew Ozz, one of the lead developers, WordPress “tentatively” plans to update to the latest version of jQuery and jQuery User Interface (UI) 1.12.1 in WordPress 5.6. The latest version of jQuery Migrate will also be added as part of the WordPress 5.6 release.

The end goal is to remove the reliance on jQuery Migrate altogether. Therefore, in WordPress 5.7 the team plans to remove jQuery Migrate, although currently this isn’t scheduled for release until 2021.

In the long term, Andrew Ozz suggested that WordPress is aiming to move the admin section to vanilla JavaScript. “There is a lot of code to migrate, so it will take a while,” he said. He also confirmed that the jQuery libraries and plugins will remain available to enqueue through Script Loader, in order to maintain backwards compatibility.

How to Future-Proof Your WordPress Website

To avoid encountering issues in the future, you should start preparing your website for WordPress 5.6 and 5.7 now. You can test how your website functions in various jQuery environments, using the Test jQuery Updates plugin.

The Test jQuery Migrate plugin for WordPress.

In WordPress 5.6, the current plan is to update to the latest version of jQuery and jQuery UI, but leave the jQuery Migrate plugin enabled. To test this setup, navigate to Plugins > Test jQuery Updates.

You can now change jQuery version to 3.5.1, and change jQuery UI to 1.12.1. You should also ensure that jQuery Migrate is set to Enabled.

Now, put your website to the test. If you encounter any unexpected behavior, you can troubleshoot these issues using a toolkit such as Chrome DevTools.

For the WordPress 5.7 release, the team plans to remove jQuery Migrate. To test your website in this environment, you should set jQuery Migrate to Disabled. You’ll also want to set both jQuery version and jQuery UI to the latest available release.

You can now test your website for any issues or errors. If you do experiment with the Test jQuery Updates plugin, remember to restore the plugin’s default settings after you’ve finished testing. Alternatively, you can deactivate or delete this plugin if it’s no longer required.

WordPress jQuery Conflict Conclusion

The WordPress jQuery conflict can cause issues with thousands of third-party themes and plugins. If you’re experiencing problems after updating to 5.5, there are steps you can take to resolve these issues:

  1. Check you have the latest version of all themes and plugins.
  2. Contact the developer about any jQuery conflicts you’re encountering.
  3. Consider whether the theme or plugin has been abandoned.
  4. Re-enable the migration script, using Enable jQuery Migrate Helper.

If you’re concerned about WordPress updates, or conflicts with your plugins and themes, your web hosting provider can offer support. At A2 Hosting, all our plans feature 24/7 support as standard. You can access support via live chat, email or phone, and all support requests are handled by our hand-selected team of WordPress experts.

Featured image credit: iStock.

The A2 Posting