All Tutorials

Include JavaScript in Shopify themes

All Tutorials

Include JavaScript in Shopify themes

Include JavaScript in Shopify themes

Three golden rules

  1. Make no assumptions
    • You cannot depend on any JavaScript being available in a Shopify theme.
    • Other apps, besides your own, may be installed and may include their own JavaScript.
  2. Use ScriptTag

    If you need to add anything to a storefront use JavaScript. Don't edit a theme's files. Add your JavaScript using a ScriptTag resource. When your app is uninstalled, your Javascript will no longer be used by the shop automatically, and that is the beauty of using a ScriptTag resource. The merchant won't need to edit his theme to bring it back to the way it was before your app's installation. Merchants will love you for that.

  3. Use a closure

    As much as you can, write your code in pure JavaScript without any library dependancy. To avoid conflict with other Javascript, wrap your code in a closure, like so:

        // Your JavaScript here

Use Ajax to load shop-specific settings in your JavaScript

Most likely, you'll be writing one JavaScript file that will be used by all of the shops that install your app. If you need to access shop-specific app settings in your static JavaScript file, use Ajax to access your own defined URL with the shop ID or domain specified in that URL. Your app will serve those shop settings in JSON format, which you can then use in your JavaScript file.

Use jQuery responsibly

If you prefer to use jQuery in your JavaScript file, you will need to load jQuery conditionally. It is not reasonable to request that a theme:

  • Already includes jQuery to run your app, or
  • Includes a relatively cutting-edge version of jQuery.

A lot of stores have older themes that use jQuery < 1.3 or Prototype.

You should always check to see if jQuery is defined, and establish your minimum version requirement. If your requirement is not met, load the jQuery you need and use it in no conflict mode, like so:

var loadScript = function(url, callback){
/* JavaScript that will load the jQuery library on Google's CDN. We recommend this code: Once the jQuery library is loaded, the function passed as argument, callback, will be executed. */
var myAppJavaScript = function($){ /* Your app's JavaScript here. $ in this scope references the jQuery object we'll use. Don't use 'jQuery', or 'jQuery191', here. Use the dollar sign that was passed as argument.*/ $('body').append('<p>Your app is using jQuery version '+$.fn.jquery+'</p>'); };
if ((typeof jQuery === 'undefined') || (parseFloat(jQuery.fn.jquery) < 1.7)) { loadScript('//', function(){ jQuery191 = jQuery.noConflict(true); myAppJavaScript(jQuery191); }); } else { myAppJavaScript(jQuery); }

By using the noConflict method, you will leave jQuery or $ alone outside the scope of your app's JavaScript. Once your app is installed, if you run the following in your console on your storefront, the result will be the version of jQuery of the theme, if that theme uses jQuery. That jQuery may be older than the one you loaded and used in your app's JavaScript:


If your application JavaScript contains the following instruction:

$('body').append('Your app is using jQuery version '+$.fn.jquery);

... what will be added to the storefront page is:

Your app is using jQuery version 1.9.1.

A slate JavaScript file to use as a starting point

Here's a good starting point for your own JavaScript file: