Skip to main content

Assets

The Assets folder serves as the central repository for all static resources that define the visual style and interactive behavior of a Soppiya theme. To ensure optimal global performance, all files stored in this directory are automatically hosted and served via Soppiya’s High-Speed Content Delivery Network (CDN) at static.soppiya.com.

Directory Structure​

Asset files are located in the /assets folder at the root of the theme hierarchy.

└── theme
    └── assets
        ├── theme.css.liquid    # Dynamic CSS
        ├── product-card.js     # Component script
        ├── brand-logo.svg      # Vector graphics
        ├── hero-video.mp4      # High-definition media
        └── icons.json          # Configuration data
note

Flat Directory Constraint: Soppiya themes do not currently support subdirectories within the /assets folder. All assets must reside directly in the root of the folder. Developers are encouraged to use descriptive naming conventions (e.g., section-header.css) to maintain organization.

Supported File Specifications​

Soppiya is designed to handle modern web formats to ensure a rich, responsive experience across all devices.

CategorySupported ExtensionsBest Practice Use Case
Styles.css, .css.liquidGlobal and component-specific styling.
Scripts.js, .js.liquidStorefront interactivity and API integration.
Images.webp, .svg, .png, .jpg, .gifProduct media, logos, and UI elements.
Video.mp4Hero banners and product demonstrations.
Fonts.woff, .woff2, .ttfCustom brand typography.
Data.jsonStatic configuration or localized datasets.

Technical Implementation: Liquid Filters​

To maintain path integrity and leverage CDN caching, you must never hardcode file paths. Instead, use Soppiya’s specialized Liquid filters to generate dynamic URLs.

The asset_url Filter​

The primary filter for retrieving the full CDN path of any file. It automatically appends a versioning string (e.g., ?v=458092) to bypass browser cache whenever a file is updated.

  • Syntax: {{ 'main.js' | asset_url }}
  • Result: https://static.soppiya.com/t/[theme_id]/assets/main.js?v=914907

The stylesheet_tag Filter​

A shortcut to generate a complete <link rel="stylesheet"> HTML element.

  • Syntax: {{ 'global.css' | asset_url | stylesheet_tag }}

The img_url & icon_url Filters​

Specialized filters for media. icon_url is optimized for Soppiya’s system icons, often utilized as mask-image sources for CSS-based color manipulation.

  • Icon Usage: 
    <div class="icon" style="mask-image: url({{ 'outline/cart.svg' | icon_url }});"></div>

Advanced Asset Optimization​

Dynamic Assets (.liquid extension)​

Soppiya allows you to use Liquid variables directly inside your CSS and JavaScript files. By appending .liquid to the filename (e.g., theme.css.liquid), the platform will parse theme settings before serving the file.

Example: Using Theme Settings in CSS

/* theme.css.liquid */
:root {
    --primary-color: {{ settings.color_primary }};
    --base-font: {{ settings.body_font | font_family }};
}

Script Loading Strategy​

For superior Core Web Vitals scores, always load non-critical JavaScript using the defer attribute.

<script src="{{ 'product-drawer.js' | asset_url }}" defer></script>

Developer Best Practices​

Image Optimization: While Soppiya supports multiple formats, we strongly recommend using .webp for photographs and .svg for logos and icons. This significantly reduces the initial page payload and improves mobile conversion rates.

tip

Modular CSS: Instead of maintaining a single monolithic stylesheet, break your styles into component-level files like cart-drawer.css or footer.css. Load these files only within the relevant Sections using the stylesheet_tag to ensure your browser only downloads the code necessary for the current page.

warning

File Name Collisions: Ensure every asset has a unique filename. If you upload a file with an identical name to an existing asset, the Soppiya engine will overwrite the previous version without warning.