Skip to main content

Theme Assets & Global CDN Delivery

Theme assets are the frontend client-side resources—such as CSS stylesheets, interactive JavaScript scripts, branding images, and custom webfonts—that govern the appearance and user experience of your SitePack storefront.

This guide details how static assets are organized, how they are optimized and served via our globally distributed CDN, and the proper syntax to link to them inside your Twig templates.

The /assets Folder Convention​

All theme assets must be located within the /assets directory at the absolute root of your theme. The standard directory contains the following subfolders:

/assets
├── css/      # Pre-minified CSS stylesheets (.css)
├── js/       # Interactive client scripts (.js)
├── img/      # Storefront graphics, icons, and SVG illustrations (.png, .jpg, .svg, .webp)
└── fonts/    # Web font resources (.woff, .woff2)

Edge-Optimized Asset Delivery System​

When you execute sitepack theme:publish (or during local synchronization with sitepack theme:watch), the SitePack asset pipeline performs optimizations to ensure maximum Core Web Vitals performance:

1. Global CDN Distribution​

Every file in your /assets folder is automatically mirrored and cached across a globally distributed Content Delivery Network (CDN). This reduces server response latency by delivering images and scripts from edge servers closest to the shopper's location.

2. No On-The-Fly Compilation or Minification​

To maintain maximum transparency, speed, and reliability of deployments, SitePack does not compile SCSS/Sass or minify/compress stylesheets on the fly.

  • Developer Build Responsibility: Developers must compile their SCSS or Sass stylesheets locally and provide a completed, production-ready build with pre-minified CSS directly inside the /assets/css/ folder.
  • Similarly, JavaScript scripts and static vector assets should be pre-optimized and minified locally before synchronizing or publishing.

3. Automatic Version Cache-Busting​

To ensure merchants and shoppers instantly see style changes when you update your theme, SitePack automatically injects dynamic version queries or hash signatures into the generated asset paths. This eliminates the "frozen style cache" problem without requiring users to clear their browser storage.

Linking Assets in Twig Templates​

To ensure your URLs are dynamically mapped to the correct, versioned, CDN-distributed endpoint, never hardcode paths to the /assets directory.

Instead, always use the built-in Twig function theme_asset() or its string filter alias asset_url.

The theme_asset() Function​

This is the standard rendering function. Pass a relative path starting from inside the /assets/ directory:

{# Link a pre-minified stylesheet #}
<link rel="stylesheet" href="{{ theme_asset('css/theme.min.css') }}">

{# Link a JavaScript file #}
<script src="{{ theme_asset('js/app.js') }}" defer></script>

{# Render an image #}
<img src="{{ theme_asset('img/brand-logo.png') }}" alt="{{ site.site.name }}">

The asset_url Filter​

As an alternative, syntactic-sugar approach, you can filter a relative path string directly using asset_url:

{# Same outcomes using the asset_url filter #}
<link rel="stylesheet" href="{{ 'css/theme.min.css' | asset_url }}">

<img src="{{ 'img/hero-background.jpg' | asset_url }}" alt="Hero Background">

Asset Performance & Optimization Best Practices​

To ensure your themes achieve perfect PageSpeed Insights scores and look beautiful, incorporate these technical standards into your local development and build pipelines:

1. Optimize Graphics and Images​

  • Prefer WebP or AVIF: Standardize image assets in .webp formats. They compress up to 30% more than JPEGs while maintaining visual quality.
  • Vectorize Icons with SVG: Use lightweight, responsive SVG files for logos, category icons, and system graphics.

2. Use Modern Local Tooling​

  • Use local modern compilation pipelines (like Vite, Webpack, PostCSS, or Tailwind CLI) to compile and minify stylesheets and bundle interactive scripts before deploying.

3. Load Non-Critical Scripts Asynchronously​

Use the defer or async attributes when loading theme-level JavaScript files to ensure scripts do not block the critical rendering path of the HTML DOM:

<script src="{{ theme_asset('js/interactive-cart.js') }}" defer></script>

4. Efficient Fonts Implementation​

  • woff2 Format Only: Keep custom fonts in the modern, optimized .woff2 format inside your /assets/fonts directory.
  • CSS Font-Display property: Use font-display: swap; inside your @font-face declarations to prevent empty-text flashes during font downloads.

Exploring Further:​

Now that you have configured styles and assets, explore the complete list of available system-wide SVG vectors in the Built-in Icons Library!