Liquid Theme Resources

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:

1. Resource Templates – These templates allow you to define and manage theme assets.
2. Require liquid tag – Use this tag to include resources in your theme dynamically.
3. 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:

```text

• 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:

```text

resources/dist/styles/my-styles.css ```

And your styles will be allocated in the content field of that theme template:

```css

.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:

```liquid

{% require ‘scripts/my-script.js’ %} ```

And to include my-style.css you would use:

```liquid

{% 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:

```liquid

{% 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 cache JavaScript and CSS files to improve performance. Theme assets are served with a long-lived, immutable cache, so a returning browser keeps using the version it already has unless the filename changes. To force the browser to load the latest version, each file must 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.

```json

{ “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.

```text

“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.

```text

“dist/scripts/my-script.v2.js” ```

⚠️ Always use a unique fingerprint for every content change

Always change the fingerprint whenever you change a resource’s content. Theme assets are served with a permanent, immutable browser cache, so the fingerprinted filename is the only thing that tells a browser to fetch the new version. If you edit a file’s content but keep the same fingerprint (for example, editing styles.v1.css in place, or reusing a token like styles.mar06.css across two different builds), returning visitors keep serving the old file from their browser cache. The cache does not expire on its own, so they see broken styling and broken cart behavior until they hard refresh or clear their cache. Incognito or a different device works because there is no cached copy. Clearing the server or CDN cache does not fix it, because the stale copy lives in each visitor’s browser.

The rules

1. Use a unique fingerprint for every content change. Never edit a resource in place under the same fingerprint, and never reuse a date or version token across different builds. If your build tool generates a content hash automatically, let it. If you set the fingerprint by hand, increment it (.v1, .v2) every time the content changes.
2. Bump CSS and JavaScript together. A stale cached script is what causes broken interactive behavior such as a dead cart, so update the fingerprint on every changed resource, not just the visually obvious ones.
3. Update both the fingerprinted filename and its entry in manifest.json in the same change.

Splitting large resource files

Salesforce theme template records have a maximum content size of approximately 131,072 characters (~128KB). If a compiled resource file exceeds this limit, it cannot be stored in a single template record.

To work around this, split the file into numbered parts and list them in manifest.json as an ordered array. StoreConnect assembles the parts transparently at render time — from the theme’s perspective, it behaves as a single file.

Step 1: Create part templates in Salesforce

Split your file content into chunks that each stay under the 131,072-character limit. Create a separate theme template for each part using a numbered naming convention:

```text

resources/dist/scripts/my-large-script.part1.js resources/dist/scripts/my-large-script.part2.js resources/dist/scripts/my-large-script.part3.js ```

Step 2: Declare the parts as an array in manifest.json

In your manifest.json template, use an array as the value instead of a single string:

```json

{ “dist/scripts/my-large-script.js”: [ “dist/scripts/my-large-script.part1.js”, “dist/scripts/my-large-script.part2.js”, “dist/scripts/my-large-script.part3.js” ] } ```

StoreConnect reads the array in order and concatenates the parts at render time. The require tag in your Liquid templates still references the logical (non-versioned) name:

```liquid

{% require ‘scripts/my-large-script.js’ %} ```

This works for scripts, styles, and any other resource type.

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.

```text

resources/dist/scripts/menu.js ```

And you will include it in your manifest.json.

```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

Troubleshooting tips

Some changes must be compiled locally

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.

Content or styles not working properly for a customer

Remember to apply unique file fingerprints to all content changes to prevent caching of superseded content. If customers report seeing something odd on your site, it could be because they are seeing a cached version. Refer to the section about unique fingerprints, above.