{"title":"Liquid theme resources","slug":"liquid-theme-resources","url":"https://support.storeconnect.com/articles/liquid-theme-resources","url_markdown":"https://support.storeconnect.com/articles/liquid-theme-resources.md","subtitle":null,"summary":"Manage JavaScript, CSS, and static assets in your theme using resource templates, the require tag, and manifest.json for versioned cache-busting. Override default base theme resources with your own.","type":"Developer_Documentation","video_url":"","keywords":"liquid theme resources, theme assets, require tag, manifest.json, resource templates, javascript, css, cache busting, asset versioning, theme overrides, liquid tags, storeconnect theme, large files, file size limit, split resource, 128kb","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"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.\n\nYou 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.\n\nTheme 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. \n\nOur Liquid Resource system consists of three key elements:\n\n1.  **Resource Templates** – These templates allow you to define and manage theme assets.\n2.  **Require liquid tag** – Use this tag to include resources in your theme dynamically.\n3.  **manifest.json Template** – This file manages with versioning of your assets.\n\n## Resource Templates\n\nLiquid 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.\n\n**Example**:\n\n```text\n\n- resources/\n  - dist/\n    - files/\n      - icon.svg\n    - scripts/\n      - my-script.js\n      - your-script.js\n    - styles/\n      - my-style.css\n      - other-style.css\n```\n\nYour my-style.css should exist as a theme template in Salesforce with the following folder structure in the Key:\n\n```text\n\nresources/dist/styles/my-styles.css\n```\n\nAnd your styles will be allocated in the content field of that theme template:\n\n```css\n\n.my-class {\n  background-color: #fafafa;\n}\n```\n\n## The Require Tag\n\nThe 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:\n\n\n```liquid\n\n{% require 'scripts/my-script.js' %}\n```\n\n\nAnd to include my-style.css you would use:\n\n\n```liquid\n\n{% require 'styles/my-style.css' %}\n```\n\n\nThis 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:\n\n\n```liquid\n\n{% require 'scripts/my-script.js', multiple: true %}\n```\n\n\n## The manifest.json Template\n\nThis 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.\n\nIf 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.\nBrowsers 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.\n\nExample JSON used in a manifest.json template.\n\n```json\n\n{\n  \"dist/scripts/my-script.js\": \"dist/scripts/my-script.SYDCGK7W.js\",\n  \"dist/styles/my-style.css\": \"dist/styles/my-style.OGVFMJSN.css\"\n}\n```\n\nIn 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.\n\nThe 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.\n\n```text\n\n\"dist/scripts/my-script.js\"\n```\n\nThe 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.\n\n```text\n\n\"dist/scripts/my-script.v2.js\"\n```\n\n## ⚠️ Always use a unique fingerprint for every content change\n\nAlways 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.\n\n### The rules\n\n1.  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.\n2.  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.\n3.  Update both the fingerprinted filename and its entry in `manifest.json` in the same change.\n\n## Splitting large resource files\n\nSalesforce 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.\n\nTo 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.\n\n### Step 1: Create part templates in Salesforce\n\nSplit 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:\n\n```text\n\nresources/dist/scripts/my-large-script.part1.js\nresources/dist/scripts/my-large-script.part2.js\nresources/dist/scripts/my-large-script.part3.js\n```\n\n### Step 2: Declare the parts as an array in manifest.json\n\nIn your `manifest.json` template, use an array as the value instead of a single string:\n\n```json\n\n{\n  \"dist/scripts/my-large-script.js\": [\n    \"dist/scripts/my-large-script.part1.js\",\n    \"dist/scripts/my-large-script.part2.js\",\n    \"dist/scripts/my-large-script.part3.js\"\n  ]\n}\n```\n\nStoreConnect 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:\n\n\n```liquid\n\n{% require 'scripts/my-large-script.js' %}\n```\n\n\nThis works for scripts, styles, and any other resource type.\n\n## Overriding Default Theme Resources\n\nEvery [resource given in our base theme repository](https://github.com/GetStoreConnect/base-theme/tree/v19.0.0/templates/resources) 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.\n\n```text\n\nresources/dist/scripts/menu.js\n```\n\nAnd you will include it in your manifest.json.\n\n```json\n\n{\n  \"dist/scripts/menu.js\": \"dist/scripts/menu.BG674J.js\"\n}\n```\n\nThe 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\n\n## Troubleshooting tips\n\n### Some changes must be compiled locally\n\nIf 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.\n\n### Content or styles not working properly for a customer\n\nRemember 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.\n\n## In this section\n\n- [Compiling Liquid theme resources](compiling-liquid-theme-resources) — build and upload resource files from a local theme project"}