Compiling Liquid Theme Resources

Directory Structure Overview

theme/ └── resources/ ├── build/ │ ├── files-config.js │ ├── helpers.js │ ├── index.js │ ├── scripts-config.js │ └── styles-config.js ├── src/ │ ├── files/ │ ├── scripts/ │ └── styles/ ├── script.liquid ├── style.liquid ├── package.json └── package-lock.json

✅ Prerequisites

Ensure Node.js is installed on your machine.

Install Node (macOS Example):

brew update brew install node

Verify installation:

node -v npm -v

🔧 Step-by-Step Instructions

1. Navigate to the Resources Directory

   cd theme/resources

2. Install Dependencies

   This installs everything from package.json:

   npm install

3. Run the Build Script

   npm run build

4. Expected Output

   [esbuild theme scripts] building... [esbuild theme scripts] ...done [esbuild theme styles] building... [esbuild theme styles] ...done [esbuild theme files] building... [esbuild theme files] ...done

🛠 Additional Commands

Command	Description
npm run build	Build scripts, styles, and files
npm run watch	Watch for changes and auto-recompile (with minify)
npm run clean	Remove dist/ and rebuild
npm run heroku-postbuild	Production build with minify and cleanup

📌 Optional Tasks

🧹 Clean

After extended development, compiled output may become bloated. You can clean and regenerate only the latest files by running:

npm run clean

This removes the dist/ directory and runs a fresh build.

🚀 Production

To prepare a final production version for deployment:

1. Clean the build:

npm run clean

1. Run a minified production build:

npm run heroku-postbuild

This generates a fully packaged and minified resources folder suitable for use with the StoreConnect Theme Importer.

📝 Minor Changes

To make minor updates to only a few scripts, styles, or assets without a full theme re-import, you can overwrite the manifest to include only the changed files.

1. Run the watch script:

   npm run watch

2. Edit the desired files:

   As you make changes to JavaScript, CSS, or static files in resources/src/, esbuild will automatically compile and generate updated hashed files in resources/dist/.

3. Deploy selective updates without full import:

   1. Open Salesforce.
   2. Navigate to the Themes tab.
   3. Open the Theme record you want to update.
   4. Navigate to the Theme Templates section.

   5. Create or update the appropriate template for each modified file. Use these template key formats:

      • Scripts: resources/dist/scripts/[dir]/[filename].[hash].js
      • CSS: resources/dist/css/[dir]/[filename].[hash].css
      • Files: resources/dist/files/[dir]/[filename].[hash].[ext]

   6. Create or modify a template with the key: resources/dist/manifest.json

      This maps updated files to their unhashed equivalents and augments the existing manifest without overwriting the full bundle. Example format:

      { "dist/scripts/bundles.js": "dist/scripts/bundles.KCS3ODL5.js", "dist/css/utils/dropdown.css": "dist/css/utils/dropdown.GRARK238.css", "dist/files/logo.png": "dist/files/logo.IJQZ82PO.png" }

📌 Notes on Hashing

The [hash] in filenames is used for browser caching. When a file changes, its hash will change. To ensure updated files are loaded, make sure:

• The new [hash] is used in both the file name and the manifest.json template.
• You’re using esbuild in watch mode or running a fresh build after edits.

🧩 Usage in the Theme

Within your Liquid templates, you should reference the unhashed resource names. The Theme engine will resolve these using manifest.json.

{% require 'scripts/bundles.js' %} {% require 'css/utils/dropdown.css' %} {% require 'files/logo.png' %}

✅ Summary

• Navigate: cd theme/resources
• Install: npm install
• Build: npm run build
• Watch: npm run watch
• Clean: npm run clean
• Prod Build: npm run heroku-postbuild