How to add a custom JavaScript file to Shopify in Liquid?

In this tutorial, I’m going to walk you through a cleaner, more organized approach to customizing your Shopify theme.

While Shopify themes generally allow the insertion of custom JavaScript via built-in sections in the theme editor, I find this method a bit messy.

It’s not the most streamlined way to integrate custom styles into your theme.

Plus, when you hand over a Shopify store to a client who isn’t tech-savvy, embedding code directly through the theme customizer can lead to accidental mishaps or bugs.

That’s why I prefer and recommend a different strategy.

We’ll be linking an external JavaScript file to your Shopify theme, consolidating all your custom scripts neatly in one place.

Let’s dive in and see how this can be done for a more efficient and safer customization process.

For the purpose of this tutorial I’m going to use the default Shopify theme which is “Dawn”.

Create the JavaScript file

Let’s start by creating a JavaScript file on your local machine.

This file will hold all those custom code you’ve been thinking about for your Shopify store.

Grab your favorite text editor for this task.

I’m a big fan of VS Code, personally.

Make sure to save your file with a “.js” extension to signify it’s a JavaScript file.

A good name for this file is “theme-custom.js”.

Why this name?

Well, it’s pretty straightforward and it helps distinguish your custom work from the standard “theme.js” file that most themes use.

Think of this naming convention as my little trick.

It’s super helpful for anyone who might take over your theme’s development down the line, especially if they don’t have access to the theme’s original repository.

Also, in Shopify themes with sections, you’ll often find JavaScript files linked to individual sections.

This setup means the scripts only load when their specific section does.

A prime example of this is the Dawn theme, which I’ll use in this tutorial.

But hey, if setting up a local file sounds like a hassle, don’t sweat it.

Shopify’s got your back with its cloud code editor, where you can create and manage files directly in the cloud.

You do not need to minimize the JavaScript file, Shopify will do that automatically when the file is requested by the browser.

Upload the file

After you’ve created the file, you need to upload the JavaScript file to your Shopify store.

Go to the Shopify admin, login inside and go to the “Online Store” menu item (marked with 1 in the image below), the “Themes” menu item (marked with 2 in the image below) will be auto selected:

Go to the “…”(3 dots) button (marked with 3 in the image above) and select “Edit code” (marked with 4 in the image above).

Now the Shopify code editor will open. Look for the “Assets” folder in the left sidebar like in the image below.

In order to see the files inside the “Assets” folder click on it and click again on the “Add a new asset” link (marked with 2 in the image below):

This action will open a pop-up that will allow you to upload the JavaScript file created above to Shopify servers. 

You have 2 options here: “Upload a file” (marked with 1 in the image below)  and “Create a blank file” (marked with 2 in the image below).

Upload a file

If you have the file created you can upload it by clicking the “Add file” button (marked with 3 in the image below):

Create the JavaScript file

If you didn’t create the file you have the option to do it here on the Shopify code editor by clicking the “Create a blank file” (marked with 1 in the image below):

In order to create the JavaScript file select the extension which in this case should be “JavaScript” (marked with 2 in the image above) and name the file “theme-custom.js” (marked with 3 in the image above).

When done click on the “Done” button (marked with 4 in the image above) and you’re done.

Now you can add any custom JavaScript code as you please.

You can do it here inside the Shopify editor or pull the file inside a local environment via Shopify CLI in order to edit the file with a code editor like VS Code.

Do not close the Shopify code editor since we are not done yet.

Link the file to Shopify

You have the JavaScript file created but for it to work and for Shopify to know that a custom JavaScript file needs to be served you need to tell that to Shopify.

This is why now, you need to link the JavaScript file to Shopify.

To do that we need to find the theme index file which is the “theme.liquid”.

Inside the Shopify code editor go to the “Layout” folder (marked with 1 in the image below) and click on the “theme.liquid” file to open it.

Add the following code (marked with 3 in the image below):

{{ 'theme-custom.js' | asset_url | script_tag }}

I recommend adding the code below the rest of the JavaScript code links inside the body tag to improve page speed.

In the example below I’ve put my custom JavaScript file exactly above the closing </body> tag.

When all is done click the “Save” button to save your changes.

Test the JavaScript file

Test the file to make sure that Shopify loads it in the front-end.

Go to your store front-end and open the developer tools by pressing ⌘  + Option + I on MAC or F12 or CTRL + ⇧ + I on Windows or Linux. These shortcuts are for Chrome browser.

After you’ve open the dev tools, reload the page by pressing ⌘ + ⇧ + R ( on MacOS ) or CTRL + F5 or CTRL + ⇧ + R (on Windows or Linux ) to do a hard reload.

Now go the “Network” tab (marked with 1 in the image below), select the JavaScript profile (marked with 2 in the image below) and type in the “Filter” box (marked with 3 in the image below) the name of your JavaScript file which in this case is “theme-custom.js”.

You should see the file (marked with 4 in the image above) but that doesn’t mean the file loaded correctly. 

This is why you need to check the “Status”. If the status is 200 (marked with 5 in the image above) then your file is loaded and whatever styles you add will work correctly.

Conclusion

In conclusion, integrating custom JavaScript into your Shopify store doesn’t have to be a daunting task.

By creating a separate “.js” file, such as “theme-custom.js”, and uploading it directly to your store, you maintain a clean, organized codebase.

This approach not only keeps your theme customization neat but also makes it easier for any future developers who might work on your site.

Remember, the key is to stay organized and follow best practices to ensure a smooth, bug-free experience for both you and your clients.