Skip to content

Developers · Assets

Assets Introduction

Last updated 7 November 2026

Assets are static files that the web server delivers directly to the browser without any server-side processing. This includes CSS stylesheets, JavaScript files, images, fonts, documents, and media files. Assets live in the directory and are served via CDN for fast, globally distributed delivery.

Directory Structure

Organize your assets into subdirectories by type:

app/assets/
  images/
    logo.png
    favicon.ico
  scripts/
    app.js
    vendor.js
  styles/
    app.css
    vendor.css
  fonts/
    custom-font.woff2

Referencing Assets in Templates

Use the filter to generate the correct URL for any asset. This filter returns the CDN-backed URL with cache-busting, so browsers always load the latest version after a deployment.

<link rel='stylesheet' href='{{ 'styles/app.css' | asset_url }}'>
<script src='{{ 'scripts/app.js' | asset_url }}'></script>
<img src='{{ 'images/logo.png' | asset_url }}' alt='Logo'>

Note

Always use the filter rather than hardcoding paths. The filter ensures your assets are served from the CDN with the correct cache headers.

Adding CSS

Place your CSS files in and reference them in your layout's section. After syncing or deploying, the styles are available on your instance immediately.

If you need page-specific CSS, use the and pattern described in Layouts to inject stylesheets from individual pages.

Adding JavaScript

Place JavaScript files in and reference them in your layout or page. For best performance, load scripts at the bottom of the body or use the attribute.

Like CSS, you can use the / pattern to load page-specific JavaScript only where it is needed.

Images and Media

Static images in the directory are served via CDN. Reference them in HTML using . For user-uploaded files, see the User Uploads section under Data and Users.

Deployment

Assets are deployed with the rest of your codebase using . During development, pushes asset changes in real time.

After deployment, assets are served from the CDN with cache-busting URLs that change automatically when the file content changes. This means browsers always load the latest version without manual cache clearing.