Upgrading an old site to jQuery 4

Why upgrade?

Many sites still run jQuery 1.x, 2.x or 3.x. Old versions have known security fixes missing (for example, older 1.x and 3.x releases had cross-site scripting issues in how they handled HTML), and old plugins written for them may stop working with modern browsers. Upgrading to the current version keeps the site supported and secure, and usually takes far less time than a rewrite.

This lesson describes a careful, repeatable process.

Step 1: find out what you have

On the live site, open the browser console and check:

jQuery.fn.jquery            // e.g. "1.12.4" or "3.7.1"

Then list everything that depends on jQuery: plugins (sliders, date pickers, validation, lightboxes), theme scripts and your own code. Search the code base for $(, jQuery, $. and plugin names. Note which pages use which plugins, because you will test each one.

Do the upgrade on a copy of the site (a staging site or your computer), never directly on the live site.

Step 2: add jQuery Migrate

The jQuery team publishes the jQuery Migrate plugin for exactly this job. Load it straight after the new jQuery. It brings back most removed features, so old code keeps working, and it logs a warning every time something old is used:

<input type="checkbox" id="agree" checked>
<p id="price">Price</p>

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<script src="https://code.jquery.com/jquery-migrate-4.0.2.js"></script>
<script>
  jQuery.migrateTrace = false;   // print each warning once, without a stack trace

  // Old code written for jQuery 1.x and 3.x
  const name = $.trim("  Asha  ");
  const isList = $.isArray([1, 2]);
  const checked = $("#agree").attr("checked");
  $("#price").css("font-size", 20);

  console.log("old code still runs:", name, isList, checked);
  console.log("font size set?", $("#price")[0].style.fontSize || "no");
</script>

JQMIGRATE: Migrate is installed with logging active, version 4.0.2
JQMIGRATE: jQuery.trim() is removed; use String.prototype.trim
JQMIGRATE: jQuery.isArray() is removed; use Array.isArray()
JQMIGRATE: Boolean attribute 'checked' value is different from its lowercased name
JQMIGRATE: Auto-appending 'px' to number-typed values for jQuery.fn.css( "font-size", value ) is removed
old code still runs: Asha true checked
font size set? no

Read the output carefully:

• The first line confirms Migrate is installed.
• Each further JQMIGRATE line names an old feature and how to replace it. In the real console each one also comes with a stack trace showing which line of your code used it (this example turns the traces off to keep the output short). jQuery.migrateMessages holds the same list, with a short code for each warning, such as [trim], that you can look up in the Migrate documentation.
• Migrate brought back $.trim, $.isArray and the old .attr("checked") behaviour, so that code still works.
• It did not bring back the automatic px for font-size: it only warns. Some changes cannot be undone by Migrate, so test the pages, not just the console.

Use the uncompressed jquery-migrate-4.0.2.js while testing. The minified .min.js build is meant for production and does not print warnings.

Step 3: fix each warning

Work through the warnings page by page. The most common ones, and their fixes:

Some changes do not show up as warnings because the old code does not fail, it just behaves differently. In jQuery 4 the main ones are:

• Automatic px is now added only to width/height (and min-/max-), margins, padding, border widths and top/right/bottom/left. Every other numeric style needs a unit.
• Focus events fire in the standard order (blur, focusout, focus, focusin), which can affect code that relied on the old order.
• JSONP: a request with dataType: "json" is no longer silently turned into JSONP when the URL contains callback=?. Ask for dataType: "jsonp" explicitly if you really need it (most APIs now use CORS instead).
• Old browsers: jQuery 4 dropped support for Internet Explorer 10 and older.

Step 4: update or replace plugins

Old plugins are the most common source of trouble. For each one:

1. Check for a newer version that supports jQuery 4.
2. If there is none, fix the few calls Migrate warns about (they are usually the same handful of removed utilities), or
3. Replace it with a maintained alternative, or with a small piece of your own code or plain JavaScript.

Step 5: test everything

Open every page type, and use every interactive feature: menus, forms, validation, sliders, tabs, modals, Ajax loading, on a phone-sized screen too. Watch the console for errors and Migrate warnings. A short written checklist of features makes this repeatable for the next upgrade.

Step 6: remove Migrate

When no warnings remain, remove the Migrate script tag, test once more, and deploy. Leaving Migrate in place costs download time and lets new code use old patterns without anyone noticing.

Upgrading from very old versions

From jQuery 1.x or 2.x, upgrade in two stages: first to 3.7.1 with jQuery Migrate 3.x, fix those warnings, then to 4.0 with Migrate 4.x. Each Migrate version only knows about the changes in its own major version, so skipping straight to 4 hides problems from the 1.x to 3.x changes.

Common mistakes

• Upgrading directly on the live site.
• Using the minified Migrate build while testing and seeing no warnings.
• Treating an empty console as proof that everything works; behaviour changes such as px do not always warn.
• Leaving Migrate in production after the work is done.
• Jumping from 1.x straight to 4.0 without the 3.x stage.

Exercise

Rewrite this jQuery 1.x code so it works in jQuery 4 without Migrate:

$("#name").bind("keyup", function () {
  var value = $.trim($(this).val());
  if ($.isNumeric(value)) $(this).css("border-width", 2).css("font-size", 18);
});

<input id="name">

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<script>
  $("#name").on("keyup", function () {
    const value = $(this).val().trim();
    if (value !== "" && Number.isFinite(Number(value))) {
      $(this).css({ "border-width": 2, "font-size": "18px" });
    }
    console.log(JSON.stringify(value), "->", this.style.fontSize || "unchanged");
  });
</script>

"4" -> 18px
"42" -> 18px