This lesson provides a comprehensive overview of the structure and conventions within a Stencil theme. We will explore the major directories, such as templates, assets, scss, and config, understanding the purpose and contents of each. We will delve into file naming conventions, best practices for organizing your theme files, and how these elements work together to define the look and feel of your storefront. By the end of this lesson, you will have a solid understanding of how a Stencil theme is organized, empowering you to effectively customize and develop your own themes.
A Stencil theme package and the Stencil CLI are powered by Node.js and by dependencies installed via the package manager npm. If you’re new to npm, note the following files and folders that are involved with these dependencies:
Templates are the key building block for your Stencil theme. There are a few standard types of templates, categorized in different locations in the templates directory:
Images, CSS, and JavaScript are contained in the assets directory, grouped as follows:
When bundled, a theme package must be 50 MB or less. Static assets, particularly large images, are the most common cause of themes exceeding this size. If your theme includes many such images, consider taking advantage of WebDAV to move assets out of the theme package itself into the cloud. See more details about how this works in the developer documentation.
Most of the top-level JavaScript files located in assets/js/theme correspond with the different Stencil page types, containing the unique functionality for a given page. The filenames usually map to the templates in templates/pages, but you can observe the exact mappings in pageClasses in assets/js/app.js.
These page JS files export a class that inherits from PageManager, which automatically sets up an onReady method that will execute when the page is ready.
The page class containing functionality initialized for all pages is located at assets/js/theme/global.js.
Cornerstone features built-in support for Sass, a CSS language extension that adds advanced features, and by default all CSS is written with Sass in .scss files.
Files in assets/scss are arranged in a hierarchy of imports. By default in Cornerstone, the initial entry point for the CSS output on every page is assets/scss/theme.scss, which is imported in the base layout templates/layout/base.html.
The Sass in assets/scss is automatically compiled into CSS by Stencil.
Three files in the root directory of your theme define settings that enable multiple variations of the theme, as well as user-editable UI elements in the Page Builder interface of the BigCommerce control panel.
The settings defined in these files can be used in your templates, JavaScript, and SCSS to inject values such as color codes, font names, size strings, or other values, or to utilize boolean values for conditional logic.
The JSON structure in config.json contains a few major areas describing your theme, its configurable settings, and its variations.
In order to preview a specific variation in your local project, specify the name of the variation when running the stencil start command.
stencil start -v Bold
The following are examples of some of the configurable settings found in config.json.
A simple Handlebars expression within templates allows you to access the value of a setting from the global theme settings_object.
Custom SASS functions are available in SCSS files to fetch and process specific config settings. The appropriate SASS function to use depends on the data type of the setting’s value and what that value is being used for in SCSS. These are often used to capture a setting’s value into a SASS variable for reuse.
In order to access settings values in JavaScript, they must first be injected in a template using a Handlebars expression.
Once a value has been injected with a specific key, it is available to access on this.context in any PageManager class.
schema.json is a companion to config.json, dealing with the same _settings_values defined there. The JSON in this file is dedicated to defining how the Page Builder visual interface interacts with those settings.
The settings array in schema.json defines the fields that will be available in Page Builder, allowing admin users to override the theme’s default values in their own storefronts where the theme is applied. Each item is mapped to a setting defined in config.json by its id. The _type_of each item (such as color, font, select, checkbox, or text) determines the type of control used to interact with the setting in the Page Builder interface.
