Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars and Stencil
Handlebars Helpers
Stencil Object Model
Stencil Objects

Assets Directory

The assets Directory

Each Stencil theme’s <theme-name>/assets/ directory contains CSS, JavaScript, and image assets that help create the design of storefront pages. A minimal <theme-name>/assets/ directory contains the files and subdirectories that you can view on the Cornerstone Github Repository.

We will go further into detail about the subdirectories within /assets/ below:

The cdn Subdirectory

The /cdn/ subdirectory is designed to contain large static assets that you will upload to a content delivery network, separately from the rest of your theme. For this reason – and by design – the contents of this directory (only) are excluded from theme bundling. For details, see Staging a Theme for CDN Delivery.

The fonts Subdirectory

The /fonts/ subdirectory contains local versions of theme-specific fonts.

The icons Subdirectory

The /icons/ subdirectory contains .svg files for icons used within a theme.

The img Subdirectory

The /img/ subdirectory contains images used in the theme’s display – background images, sprites, and other images not related to store content.

You would typically reference these image assets using Stencil’s cdn Handlebars helper. For example, generically:

<img src="{{cdn 'assets/img/image.jpg'}}">

Or, with a realistic file name:

<img src="{{cdn 'assets/img/size-chart.png'}}">

Akamai Image Manager

For Stencil themes only, images that use the default zoom library pass through Akamai Image Manager. This chooses the best image to serve based on device. To bypass the image optimization, include imbypass=on as a query parameter in the image url. This will serve un-optimized images.

<img src="{{cdn 'webdav:img/image.jpg?imbypass=on'}}">

<img src="{{getImage settings.store_logo.image 'logo_size'}}?imbypass=on">

<img src="{{cdn 'assets/img/image.jpg?imbypass=on'}}">

The js Subdirectory

The /js/ subdirectory contains general JavaScript files used in the theme.

The scss Subdirectory

The /scss/ subdirectory contains theme-specific CSS resources.

Production-Safe Image References

To avoid unexpected 404 errors on your production store, we recommend that you use short relative paths in your SCSS to reference images in your /img/ subdirectory. So, for example, use references of the form: background: url('../img/header-bg.png'); rather than references of the form: background: url('/assets/img/header-bg.png');

Video Demo

Watch a video tour of the /assets/ directory, its /scss/ subdirectory, interactions between CSS and config.json values, Stencil custom Sass functions, and the /img/ subdirectory.

Directory and File Restrictions/Permissions

This section’s remaining pages list certain restrictions on changing some subdirectories’ structure, contents, and file names.

In parts of your theme’s directory tree where you are free to add new subdirectories and files, be sure to:

  • Set newly added directories to permission 755 (drwxr-xr-x).
  • Set newly added files to permission 644 (rw-r--r--).
  • Without these permissions, running your theme locally will fail, with multiple error messages. Bundling your theme will also fail, blocking its upload to a store.