Theme resources allow you to access built in assets, create your own version of any asset, and use them in your theme however you want.
You can customize your JavaScript, CSS, and other assets directly within your theme. Every resource can be stored within a template and loaded only when requested. This way you are not loading scrips and CSS not needed for that page and thus improving performance.
Theme resources are extremely useful for improving site performance, keeping modular code, having quick access to our internal resources and having well-structured theme-requiring assets like CSS, Javascript and SVG when needed instead of printing them on every single content request even if they aren't needed.
Our Liquid Resource system consists of three key elements:
- Resource Templates – These templates allow you to define and manage theme assets.
- Require liquid tag – Use this tag to include resources in your theme dynamically.
- manifest.json Template – This file manages with versioning of your assets.
Resource Templates
Liquid resource templates live in your themes template section, in the resources folder. Inside this folder, there is a folder called "dist", and inside the dist folder there are three more folders, "files", "scripts", and "styles". This is where you put the final files that you want to include in your theme.
Example:
- resources/
- dist/
- files/
- icon.svg
- scripts/
- my-script.js
- your-script.js
- styles/
- my-style.css
- other-style.css
Your my-style.css should exist as a theme template in Salesforce with the following folder structure in the Key:
resources/dist/styles/my-styles.css
And your styles will be allocated in the content field of that theme template:
.my-class {
background-color: #fafafa;
}
The Require Tag
The require tag is used to include resources in your template and specifies the path to the resource. The path is the name of your file not including the dist folder. For example, to load my-script.js for use by this template, you would use:
{% require 'scripts/my-script.js' %}
And to include my-style.css you would use:
{% require 'styles/my-style.css' %}
This will include the file in your theme in the location where the require tag is used. However, if you require the same file multiple times, it will only be included once, in the location it is first loaded. If you do want to load the same file multiple times in the same template, you can use the require tag with the multiple option:
{% require 'scripts/my-script.js', multiple: true %}
The manifest.json Template
This template serves as a mapping tool to accurately reference all resources. All resources that you want to make available in your theme should be listed in the manifest file, making them available to all your theme templates, including pages, blocks, layouts, and snippet templates.
If it doesn't already exist in your theme, you will need to add this template to your theme in Salesforce using the resources/dist/manifest.json key. Using the correct JSON format within the content field is essential for this to work. Browsers generally cache JavaScript and CSS files to improve performance, meaning that when you update a template, the browser may continue using the old version until the cache expires. To force the browser to load the latest version, each file should have a unique name. A common approach is appending a version identifier (or fingerprint) to the filename.
Example JSON used in a manifest.json template.
{
"dist/scripts/my-script.js": "dist/scripts/my-script.SYDCGK7W.js",
"dist/styles/my-style.css": "dist/styles/my-style.OGVFMJSN.css"
}
In the example above, a fingerprint is appended to the filename. Your files must include this fingerprint in the key field to ensure proper versioning. Do not include "resources/" at the beginning of the the key as the system accounts for that so does not expect it.
The first parameter specifies the non-versioned name of your template and is what you reference when using the require tag on any of your templates. This template does not have to exist as is just a static name that allows your require tag to load the current version (the second parameter) of your resource.
"dist/scripts/my-script.js"
The second parameter represents the location and the version of your resource. The fingerprint may be added by your editing tool, but if not, add your own unique fingerprint to specify the version. E.g. .v1, .v2, etc.
"dist/scripts/my-script.v2.js"
Overriding Default Theme Resources
Every resource given in our base theme repository can be overridden. Given the file structure, dependencies and code structure, you will need to create your version of each resource. For example, you can modify menu.js and create your own logic.
resources/dist/scripts/menu.js
And you will include it in your manifest.json.
{
"dist/scripts/menu.js": "dist/scripts/menu.BG674J.js"
}
The example above will replace the default menu.js provided by the StoreConnect app with your own template that has this key: dist/scripts/menu.BG674J.js
Important Note
If you want to make minor tweaks to a resource—such as a JavaScript file—you’ll need to compile it locally using your build tools. This is because our existing modules have dependencies. If you were to try and override menu.js by using import statements at the top of the file, you may encounter errors. That’s because the modules being imported exist in the backend theme, not in your custom theme.