How to upgrade to the latest version of jQuery

Modern JavaScript and web browsers have made writing JavaScript much easier. Most of the functionality of jQuery, has vanilla JavaScript equivalents. Those equivalents run faster, they don't require a large JavaScript library like jQuery. The result is they're also more secure.

Because going jQuery free is generally better for performance and security - it is recommended to either not use jQuery, or use the latest version available.

For older websites, it's not as simple. Removing jQuery can break existing old code on the website. If there's a lot of JavaScript on a website it may be hard to remove jQuery all together. In that situation it's often much easier to upgrade to the latest version of jQuery. 

Upgrading to the latest version of jQuery makes your website more secure, and potentially a little faster in terms of script execution time and loading time. If you are using a jQuery version provided through the HubSpot website page settings UI, we recommend upgrading jQuery or updating your site to no longer need jQuery.

This guide will walk you through the steps to upgrade to a newer version of jQuery. You will open the developer tools in your web browser

Before we switch versions, it's important to be aware of what areas of the site currently use jQuery. Once we know that, we know what functionality to test to ensure the new version is working.

Open the homepage of your website.

Now in your address bar, add ?hsNoJQuery=true&hsDebug=true to the end of the URL, and hit enter.

https://www.my-website.com/?hsNoJQuery=true&hsDebug=true

You added query parameters. This specific one tells HubSpot to disable jQuery when loading the page. This only affects what you see and doesn't break the site for other visitors.

Now right-click anywhere on the page and choose "inspect". The exact wording may differ slightly depending on which web browser you're using. This is the developer tools for your web browser. 

You should see a tab in the panel that opened, which says "console". Open that tab.

On pages that require jQuery you will see this error message:

"Uncaught ReferenceError: $ is not defined"

That error should also state a file name that's producing that error.

In the example image above, the two files are vast-main.js and the module js file.

Copy and paste or enter that file name somewhere you can reference later. You do not need to worry about exact spelling. Taking a screenshot you can refer to later is an alternative. Repeat this for all instances of this error you see. 

Note the page you saw those errors on.

Now we're going to do this same thing for a few other pages on your site. The best pages to do this on are ones with the most interactivity. Things like forms, dropdown menus, buttons that do something aside from bringing you to a new page. If you don't see this error on a page, great news, it doesn't use jQuery.

Once you've noted those file names somewhere let's move on to the main test.

In this step we're going to add code to test if migrating to the newest version of jQuery will break anything for your site. 

We're going to open the HubSpot website settings. Copy and paste a snippet of code, and disable jQuery. 

In a new tab, open HubSpot, navigate to Settings (gear icon). Then Website > Pages.

Scroll to down until you see jQuery.

First check that the "Include jQuery" checkbox is enabled.

If it is not, and you know jQuery is used, it was likely added by a developer. In that instance see Advanced troubleshooting . If it's enabled however, proceed.

Check the jQuery version number that's currently selected.

Copy the code below and paste it into your footer HTML, do not save yet.

Scroll back down until you see the settings for jQuery.

Check the jQuery version number that's currently selected. 

If you have version 1.7 skip to the next step. If you have version 1.1 Where you see {% set oldjQueryVersion = 1.7 %} change the number 1.7 to 1.11. This ensures the correct version of jQuery will load on your site during testing.

Now check if the checkbox for "Load HubSpot's included jQuery library from your footer" is enabled. 

If it's disabled, where you see{% set oldjQueryLocation = "footer" %}, change the "footer" text to say "head".

Find the jQuery checkbox and disable it.

Save the settings.

In the tab with your website, click into the address bar again, add ?latest_jquery=true to the end of the URL, hit enter.

You are viewing what the page looks and functions like with the latest version of jQuery.

If you closed the developer tools before, reopen them by right clicking and inspecting anywhere on the page.

Look in the console for those Uncaught ReferenceError: $ is not defined errors. If you don't see one, congratulations you followed step 2 correctly. If you see any errors or warnings that were not there prior see Advanced troubleshooting.

Now review your list of pages and files you logged earlier. Go to the pages that had those errors and add the query parameter ?latest_jquery=true to the URL and hit enter.

If everything went smoothly you shouldn't see any new errors and you shouldn't see any  Uncaught ReferenceError: $ is not defined errors.

Click around the pages on anything that's intended to be interactive on the page, dropdowns, forms, search fields etc. If everything works as expected you should be able to transition safely.

Loading jQuery from the footer is better for performance than loading in the head. If you previously needed to set  oldjQueryLocation to "head" you can improve page load times by making an update to the code. If you did not need to do that, skip to step 4, you're already loading from the footer.

Go back to your site settings where your the code is. Immediately below  there are two require_js functions. Remove the ,oldjQueryLocation from those two functions. Do not remove it from the require_js functions within the else statement -- that code is being used on your site while you are testing.

Now repeat the same testing you did with the ?latest_jquery=true parameter. Again check all of the same pages, looking for Uncaught ReferenceError: $ is not defined. 

What you're testing for this time is whether moving this script to your footer will break any scripts on your site. 

If you test all of the pages with the query parameter and don't find any of those errors then congratulations, you will be able to load jQuery in the footer. Carry on to the next step.

If you did find those errors, you have two options.

• Continue loading jQuery from the head, this will result in slower web page performance but you'll be done upgrading to the latest jQuery.
• Go through the modules and templates in your site to identify where there is JavaScript that is not waiting for jQuery to be loaded before executing. Fix those issues. If you are not a developer you'll want to find a developer to assist.

Now that you know upgrading will go smoothly, go back to your website page settings tab.

Remove the code you added previously to your footer HTML and replace it with the code below. Do not save yet.

This code will place the code in your site footer. If your old jQuery code was in the footer, or you were successful in the optional performance opportunity step above You are ready to save the settings.

If you were unsuccessful in moving jQuery to the footer in the optional performance opportunity step, change newLocation = "footer" to newLocation = "head"

You are now ready to save the settings.

Congratulations you've successfully upgraded to the latest version of jQuery.

If you're not a developer, and you've followed the other steps and have a problem, it is recommended you find a developer to assist. If you do not have a go-to developer, we recommend you reach out to one of our Solutions Partners. 

For developers we recommend reviewing the official jQuery upgrade guide. You may need to update old JavaScript to no longer use deprecated functionality. Use the migrate plugin in development mode to identify the issues and fix them one by one.

If you hit a snag, it may be helpful to ask for help in the official jQuery forums.