CSS & Asset Editing
Stylesheets, JavaScript, images, and fonts — what lives in assets/ and how to use it.
The assets/ folder holds every static file your theme serves — stylesheets, JavaScript, images, fonts, icons. Storra serves these files directly with cache-friendly headers, no processing.
Referencing assets in Liquid
Always use the asset_url filter to reference an asset. The filter resolves the file's URL, which includes a content-hash so browsers cache aggressively but pick up your changes instantly when you publish.
<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
<script src="{{ 'theme.js' | asset_url }}"></script>
<img src="{{ 'logo.png' | asset_url }}" alt="Logo">Don't hard-code paths like /assets/theme.css — they'll break or fail to invalidate when you re-publish.
CSS
The convention is a single theme.css in assets/ imported once from layout/theme.liquid. You can split into multiple files (e.g. theme.css, responsive.css) and link each one separately, or use CSS @import rules at the top of a single stylesheet.
Storra serves CSS as-is — no preprocessing, no minification. If you want Sass / Less / Tailwind, develop locally, build to plain CSS, and import the compiled output via Importing a theme.
Theme variables in CSS
Themes typically expose CSS custom properties for colors, spacing, and typography that mirror the visual editor's theme settings. Reference them in your custom CSS so settings changes propagate automatically:
.my-button {
background: var(--color-primary);
color: var(--color-primary-foreground);
padding: var(--space-md);
border-radius: var(--button-radius);
}JavaScript
Drop .js files in assets/ and reference them from your layout or sections via <script src="{{ 'my-script.js' | asset_url }}">.
Keep scripts small — heavy bundles slow down your storefront. Most stores need only a few hundred lines of vanilla JavaScript: a cart drawer toggle, a search-as-you-type box, a hamburger menu. If you're reaching for a framework, consider whether the visual editor + a small sprinkle of custom JS solves the problem first.
Loading order
Scripts loaded synchronously in <head> block page rendering until they fetch and parse. Use defer for scripts that don't need to run before the page paints, or async for scripts that don't depend on the DOM at all.
<script src="{{ 'theme.js' | asset_url }}" defer></script>Images
Images in assets/ are served directly. For storefront images that you want resized for different devices, use the image_url filter (works on package images and theme assets):
<img src="{{ 'hero.jpg' | asset_url | image_url: '1280x' }}" alt="...">The size token (1280x) requests an image at most 1280px wide, height proportional. The image_url filter handles the resizing on Storra's CDN — you upload one source image, customers get the right size for their device.
Fonts
Drop font files (.woff2 recommended) in assets/ and use @font-face in your CSS:
@font-face {
font-family: "MyBrand";
src: url("{{ 'mybrand.woff2' | asset_url }}") format("woff2");
font-display: swap;
}
body {
font-family: "MyBrand", system-ui, sans-serif;
}For Google Fonts, link them in layout/theme.liquid:
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">To wire a custom font into theme settings (so merchants can pick it from a dropdown), edit the theme's font config in config/settings_schema.json — see Typography & theme settings.
FAQ
Why is my asset returning 404?
The most common cause is hard-coding the URL. Use the asset_url filter — Storra resolves the file's actual location, including the cache-busting hash.
Can I use external libraries from a CDN?
Yes — drop the <script src="..."> in layout/theme.liquid. Be aware: external CDNs can go down, and your storefront's performance depends on theirs. Self-hosting in assets/ is more reliable.
Are there file-size limits on assets?
Each file has a size cap (typically a few megabytes; the editor warns you if you upload something too large). For very large media — videos, downloads — host them externally and reference the URL from your theme.
How do I delete an asset?
Right-click the file in the file tree and choose Delete. Make sure no Liquid file still references it before you publish, otherwise customers will see broken images or 404s.
Updated recently