Stencil Theme Structure

Like most theme systems, Stencil expects files in specific folders with specific roles. Once you know the layout, any Stencil theme — a stock one or a heavily customized one — is navigable the same way.

The folders

templates/
  pages/
    product.html
    category.html
    home.html
  components/
    products/product-card.html
  layout/
    base.html
assets/
  scss/
  js/
lang/
  en.json
config.json
schema.json

templates/pages and layout

templates/layout/base.html is the outer shell every page shares — head, header, footer — with a placeholder where each specific page's content gets inserted. templates/pages/ holds one file per page type: product.html renders a single product page, category.html renders a category listing, and so on.

components

templates/components/ holds reusable partial templates, included from other templates with Handlebars' {{> partial-name}} syntax — the direct equivalent of a Shopify snippet:

{{#each category.products}}
  {{> components/products/product-card this}}
{{/each}}

config.json in depth

config.json is the theme's manifest, declaring metadata (name, version, author) and, importantly, its template variations — named presets of settings (say, a "Light" and "Dark" variation of the same theme) that a merchant can switch between without editing any code:

{
  "name": "My Theme",
  "version": "1.0.0",
  "variations": [
    { "name": "Light", "settings": { "color-primary": "#222222" } },
    { "name": "Dark", "settings": { "color-primary": "#f5f5f5" } }
  ]
}

schema.json in depth

schema.json defines the settings a merchant can change in the Theme Editor (colors, fonts, layout options) — the same role settings_schema.json plays in a Shopify theme. Each entry declares a type (color, checkbox, dropdown, and more), and the value a merchant picks becomes available in templates through the theme settings object.

The Stencil CLI workflow

Local development happens through the stencil-cli npm package: stencil init connects a local folder to a specific store via API credentials, stencil start serves a live local preview rendered against that store's real catalog data (with live reload on file changes), and stencil push/stencil bundle package the theme for upload to the BigCommerce control panel. This mirrors the same "develop locally against live data" workflow Shopify's own CLI provides.