Upgrading jQuery 1.x to version 3.x

I was recently tasked with upgrading jQuery from 1.9 all the way up the latest version of 3.x (3.4). And I seriously thought “There is no way jQuery is on version 3 already!”. How wrong I was. Thankfully I wasn’t the only one thinking this, a few of my colleagues were on my wavelength too! So yes, jQuery is really on 3.x and 1.x is actually really, really old! This article aims to help those of you in the same situation as me with some of the common pitfalls you may encounter. Some of this is semi-specific to Drupal 7 and I’ll mention this where possible. Let's get into it.

A few quick gotchas before I list the most common bits of deprecated jQuery code to look out for:

• A LOT of 3rd party plugins are NOT up-to-date. Some I found haven’t been updated since 2010! As you know, in our world, that is a very, very long time. Please do check the pull requests tab for these 3rd party plugins hosted on github, 90% of the time you’ll find that a member of the community has forked the plugin and made it up-to-date and compliant with the latest versions of jQuery.

• The jQuery Migrate plugin. From a Drupal point of view, this plugin caused so many more problems than it solved. I ended up turning it off and individually fixing the errors with deprecated code instead. This plugin is supposed to make life easy by “Pollyfilling” your current code. Whilst in some cases it did this, many others it didn’t fix problematic code and in turn didn’t produce any errors; like finding needles in haystacks… a very frustrating experience!

• A Drupal specific gotcha: Drupal is bundled with a plugin called ba-bbq. This is 10 years out of date and contains $.browser which we’ll go into down below. You can use dadario's fork of the plugin to solve any legacy issues. Be sure to swap it in with hook_js_alter.

$(window).load() is no longer a thing

This is probably the most common thing to look out for (talking from my experience and the sheer number of stackoverflow posts!). Any instance or use of $(window).load() in your jQuery code will need replacing. It was marked deprecated as of version 1.8 and fully removed in 3.x. In its place, you will need to bind the .on() function instead. The project I was going through had mixed usage of $(window).load() and $(window).on(‘load’), so I was quite lucky considering. But still, it's an easy change, see below for an example.

$(window).load(function() {
  // insert code
}

$(window).on('load', function() {
  // insert code
}

You can no longer use $.browser to detect the current browser and/or user agent

Yup, that’s right folks, $.browser is gone. This is definitely the second most common thing I had to update across the board, in particular 3rd party plugins. I mostly found $.browser in 3rd party plugins rather than our own code. The most common use case, I think, for $.browser is to check for IE. You can replace $.browser quite easily using the line of code below or by testing features using Modernizr - no dramas here!

if ($.browser == 'MSIE') {
  // I am IE
}

const regex = RegExp('MSIE*');
if (regex.test(navigator.userAgent)) {
  // I am IE
}

this.selector is no longer a property

So a new one for me, didn’t realise this was a thing! At the very top level of a jQuery object, there is a property called “selector” and it contains the selector that the object is attached to/referencing. Who’d have guessed! Anywho, this got removed as of jQuery 3.x so any reference to it needs completely re-writing in this particular case. I found this.selector in a third party plugin we use and since we had this plugin in our repo (over using something like gulp/npm), I simply removed the line of code since it had little or no bearing on how the plugin worked. Of course, if there is code that checks what this selector is then that'll need re-writing.

andSelf() has been replaced with addBack()

So the method andSelf() has been removed in favour of addBack(). In jQuery land, a very straight forward change; simply swap out the method name. In Drupal land however, a slightly different story. The andSelf() method can be found in forms.js - a very integral Drupal core file. Swapping out this file will require a core patch. Thankfully, a member of the community (yes, me, totally me) has done just this, my patch against core will fix this issue initially. For those who are using the jQuery update contrib module, you can find a patch I made which is better suited to the entire upgrade process - this patch will get you up to 3.4.1 in addition to some other goodies, too. You’re welcome. #shamelessPlug

$.cookie issues when running two versions of jQuery at the same time.

Despite this being an extremely niche issue and not strictly being a 3.x issue I did find a few other people running into this issue too which was enough for me to put it into this guide. Plus, it’s very plausible you may end up with two versions of jQuery during this process on the same page at the same time. Basically, if for whatever reason you happen to be exposing two jQuery versions in your DOM on the same page $.cookie gets VERY confused and refuses to do it’s job properly. Easy fix. Remove one of your jQuery script tags and profit :)

And that is about it. These were my most common findings during my time upgrading jQuery. I'm sure this list is only the start of it, so if there are anymore/common bits that we may have missed, please do share them with us in the comments section below!

I hope those of you who come across this guide find it helpful and good luck for the jQuery upgrade :)