BigCommerce Stencil Theme Development
Before writing code
Fetch live docs:
- Fetch
https://docs.bigcommerce.com/developer/docs/storefront/stencil/overview for Stencil overview
- Fetch
https://docs.bigcommerce.com/developer/docs/storefront/stencil/themes/context/object-reference/elements for theme object reference
- Web-search
site:developer.bigcommerce.com stencil handlebars helpers for Handlebars helper reference
Architecture
How Stencil Works
Stencil is BigCommerce's server-rendered theme engine:
- Template files (Handlebars
.html) define page structure
- Front matter (YAML) at the top of each template declares what data to fetch
- BigCommerce injects theme objects (product, category, cart, settings, etc.) into the template context
- Handlebars helpers and partials render the data
- SCSS compiles to CSS, JS bundles with webpack
- Stencil CLI provides local development with hot reload
Template Hierarchy
templates/
├── layout/
│ ├── base.html # Master layout — header, footer, body
│ └── empty.html # Minimal layout (checkout, etc.)
├── pages/
│ ├── home.html # Homepage
│ ├── product.html # Product detail page
│ ├── category.html # Category listing
│ ├── cart.html # Cart page
│ ├── checkout.html # Checkout page
│ ├── account/ # Customer account pages
│ └── ...
├── components/
│ ├── common/ # Header, footer, navigation
│ ├── products/ # Product cards, options, gallery
│ ├── cart/ # Cart items, totals
│ └── ...
└── ...
Front Matter
What It Does
YAML block at the top of template files that declares data requirements:
---
product:
videos:
limit: {{theme_settings.product_videos_count}}
reviews:
limit: {{theme_settings.product_reviews_count}}
related_products:
limit: {{theme_settings.related_products_count}}
similar_by_views:
limit: {{theme_settings.similar_by_views_count}}
---
How It Works
- BigCommerce reads the front matter before rendering
- Fetches the specified data from its APIs
- Injects results into the Handlebars template context
- Controls what data is available on each page
Common Front Matter Resources
product — product details, images, videos, reviews, related products
category — category info, products in category
cart — cart items, totals
customer — logged-in customer data
shop_by_brand — brand listing
new_products, featured_products, top_products — product collections
Theme Objects
Key Objects
| Object |
Available On |
Contains |
product |
Product page |
name, price, images, options, variants, description, reviews |
category |
Category page |
name, description, products, subcategories |
cart |
Cart page |
items, subtotal, taxes, grand_total |
customer |
When logged in |
name, email, addresses, orders |
settings |
All pages |
store name, currency, logo, URLs |
theme_settings |
All pages |
config.json setting values |
breadcrumbs |
Most pages |
navigation breadcrumbs |
page |
CMS pages |
title, content, URL |
Accessing Data
{{product.title}}
{{product.price.without_tax.formatted}}
{{#each product.images}}
<img src="{{getImage this 'product_size'}}" alt="{{this.alt}}">
{{/each}}
Handlebars Helpers
Control Flow
{{#if condition}}...{{else}}...{{/if}} — conditional
{{#unless condition}}...{{/unless}} — inverse conditional
{{#each collection}}...{{/each}} — iteration
{{#with object}}...{{/with}} — context shifting
BigCommerce Custom Helpers
{{getImage image 'size_name'}} — generate image URL at specific size
{{cdn 'path/to/asset'}} — CDN-prefixed asset URL
{{stylesheet 'path/to/css'}} — include stylesheet
{{inject 'variable' value}} — pass data to JavaScript context
{{jsContext}} — output injected variables as JSON for JS consumption
{{lang 'translation_key'}} — internationalization
{{money price}} — format currency
{{truncate text length}} — truncate string
{{any collection}} — check if collection has items
{{all condition1 condition2}} — logical AND
{{compare a '===' b}} — comparison
Partials
Include reusable template fragments:
{{> components/products/card product}} — render a partial with context
{{> components/common/header}} — include a component
- Partials live in
templates/components/
Styling (SCSS)
Structure
assets/scss/
├── settings/ # Variables, mixins
│ ├── foundation/
│ └── citadel/
├── components/ # Component styles
├── layouts/ # Layout styles
├── tools/ # Utility mixins
└── theme.scss # Main entry point
Theme Settings in SCSS
Access config.json values: stencilColor("primary"), stencilNumber("font-size"), stencilString("font-family")
JavaScript
Module System
Stencil uses webpack for JS bundling:
- ES6 module imports
- Entry point in
assets/js/app.js
- Page-specific modules loaded conditionally
- jQuery available globally (Cornerstone ships with it)
Accessing Theme Data in JS
Use {{inject}} in templates and {{jsContext}} to pass server data to client JS:
{{inject 'productId' product.id}}
<script>{{jsContext}}</script>
Access in JS via this.context in PageManager subclasses.
PageManager
Cornerstone's page lifecycle manager:
- Extend
PageManager for page-specific JS
onReady() — DOM ready, initialize functionality
- Registered per page type in
assets/js/app.js
Configuration
config.json
Theme configuration with settings and variations:
settings — default values for all theme settings
variations — named presets (Light, Bold, Warm, etc.)
read_only_files — files that cannot be edited in Theme Editor
schema.json
Defines the Theme Editor UI:
- Sections, groups, and fields that appear in the visual editor
- Field types:
color, font, select, checkbox, text, range, imageDimension
- Maps to
config.json settings keys
Best Practices
- Fork Cornerstone as your starting point — don't start from scratch
- Use front matter to control data loading — don't over-fetch
- Use
{{inject}} to pass data to JS — don't scrape the DOM
- Use
{{cdn}} for all asset URLs — ensures CDN delivery
- Define schema.json entries for all customizable settings
- Use SCSS variables linked to config.json for consistent theming
- Escape user content:
{{{sanitize html}}} for HTML, {{variable}} auto-escapes
- Test across theme variations
- Keep bundle size small — conditionally load JS per page
Fetch the Stencil documentation and theme object reference for exact helper syntax, front matter keys, and object structure before implementing.
1---2name: bc-stencil3description: Build BigCommerce Stencil themes — Handlebars templates, front matter, theme objects, SCSS, JavaScript modules, config.json, schema.json, and Stencil CLI. Use when creating or customizing BigCommerce storefront themes.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/bc-stencil7---89# BigCommerce Stencil Theme Development1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.bigcommerce.com/developer/docs/storefront/stencil/overview` for Stencil overview152. Fetch `https://docs.bigcommerce.com/developer/docs/storefront/stencil/themes/context/object-reference/elements` for theme object reference163. Web-search `site:developer.bigcommerce.com stencil handlebars helpers` for Handlebars helper reference1718## Architecture1920### How Stencil Works2122Stencil is BigCommerce's server-rendered theme engine:231. Template files (Handlebars `.html`) define page structure242. **Front matter** (YAML) at the top of each template declares what data to fetch253. BigCommerce injects **theme objects** (product, category, cart, settings, etc.) into the template context264. Handlebars helpers and partials render the data275. SCSS compiles to CSS, JS bundles with webpack286. Stencil CLI provides local development with hot reload2930### Template Hierarchy3132```33templates/34├── layout/35│ ├── base.html # Master layout — header, footer, body36│ └── empty.html # Minimal layout (checkout, etc.)37├── pages/38│ ├── home.html # Homepage39│ ├── product.html # Product detail page40│ ├── category.html # Category listing41│ ├── cart.html # Cart page42│ ├── checkout.html # Checkout page43│ ├── account/ # Customer account pages44│ └── ...45├── components/46│ ├── common/ # Header, footer, navigation47│ ├── products/ # Product cards, options, gallery48│ ├── cart/ # Cart items, totals49│ └── ...50└── ...51```5253## Front Matter5455### What It Does5657YAML block at the top of template files that declares data requirements:5859```yaml60---61product:62 videos:63 limit: {{theme_settings.product_videos_count}}64 reviews:65 limit: {{theme_settings.product_reviews_count}}66 related_products:67 limit: {{theme_settings.related_products_count}}68 similar_by_views:69 limit: {{theme_settings.similar_by_views_count}}70---71```7273### How It Works7475- BigCommerce reads the front matter before rendering76- Fetches the specified data from its APIs77- Injects results into the Handlebars template context78- Controls what data is available on each page7980### Common Front Matter Resources8182- `product` — product details, images, videos, reviews, related products83- `category` — category info, products in category84- `cart` — cart items, totals85- `customer` — logged-in customer data86- `shop_by_brand` — brand listing87- `new_products`, `featured_products`, `top_products` — product collections8889## Theme Objects9091### Key Objects9293| Object | Available On | Contains |94|--------|-------------|----------|95| `product` | Product page | name, price, images, options, variants, description, reviews |96| `category` | Category page | name, description, products, subcategories |97| `cart` | Cart page | items, subtotal, taxes, grand_total |98| `customer` | When logged in | name, email, addresses, orders |99| `settings` | All pages | store name, currency, logo, URLs |100| `theme_settings` | All pages | config.json setting values |101| `breadcrumbs` | Most pages | navigation breadcrumbs |102| `page` | CMS pages | title, content, URL |103104### Accessing Data105106```handlebars107{{product.title}}108{{product.price.without_tax.formatted}}109{{#each product.images}}110 <img src="{{getImage this 'product_size'}}" alt="{{this.alt}}">111{{/each}}112```113114## Handlebars Helpers115116### Control Flow117118- `{{#if condition}}...{{else}}...{{/if}}` — conditional119- `{{#unless condition}}...{{/unless}}` — inverse conditional120- `{{#each collection}}...{{/each}}` — iteration121- `{{#with object}}...{{/with}}` — context shifting122123### BigCommerce Custom Helpers124125- `{{getImage image 'size_name'}}` — generate image URL at specific size126- `{{cdn 'path/to/asset'}}` — CDN-prefixed asset URL127- `{{stylesheet 'path/to/css'}}` — include stylesheet128- `{{inject 'variable' value}}` — pass data to JavaScript context129- `{{jsContext}}` — output injected variables as JSON for JS consumption130- `{{lang 'translation_key'}}` — internationalization131- `{{money price}}` — format currency132- `{{truncate text length}}` — truncate string133- `{{any collection}}` — check if collection has items134- `{{all condition1 condition2}}` — logical AND135- `{{compare a '===' b}}` — comparison136137### Partials138139Include reusable template fragments:140- `{{> components/products/card product}}` — render a partial with context141- `{{> components/common/header}}` — include a component142- Partials live in `templates/components/`143144## Styling (SCSS)145146### Structure147148```149assets/scss/150├── settings/ # Variables, mixins151│ ├── foundation/152│ └── citadel/153├── components/ # Component styles154├── layouts/ # Layout styles155├── tools/ # Utility mixins156└── theme.scss # Main entry point157```158159### Theme Settings in SCSS160161Access `config.json` values: `stencilColor("primary")`, `stencilNumber("font-size")`, `stencilString("font-family")`162163## JavaScript164165### Module System166167Stencil uses webpack for JS bundling:168- ES6 module imports169- Entry point in `assets/js/app.js`170- Page-specific modules loaded conditionally171- jQuery available globally (Cornerstone ships with it)172173### Accessing Theme Data in JS174175Use `{{inject}}` in templates and `{{jsContext}}` to pass server data to client JS:176```handlebars177{{inject 'productId' product.id}}178<script>{{jsContext}}</script>179```180Access in JS via `this.context` in PageManager subclasses.181182### PageManager183184Cornerstone's page lifecycle manager:185- Extend `PageManager` for page-specific JS186- `onReady()` — DOM ready, initialize functionality187- Registered per page type in `assets/js/app.js`188189## Configuration190191### config.json192193Theme configuration with settings and variations:194- `settings` — default values for all theme settings195- `variations` — named presets (Light, Bold, Warm, etc.)196- `read_only_files` — files that cannot be edited in Theme Editor197198### schema.json199200Defines the Theme Editor UI:201- Sections, groups, and fields that appear in the visual editor202- Field types: `color`, `font`, `select`, `checkbox`, `text`, `range`, `imageDimension`203- Maps to `config.json` settings keys204205## Best Practices206207- Fork Cornerstone as your starting point — don't start from scratch208- Use front matter to control data loading — don't over-fetch209- Use `{{inject}}` to pass data to JS — don't scrape the DOM210- Use `{{cdn}}` for all asset URLs — ensures CDN delivery211- Define schema.json entries for all customizable settings212- Use SCSS variables linked to config.json for consistent theming213- Escape user content: `{{{sanitize html}}}` for HTML, `{{variable}}` auto-escapes214- Test across theme variations215- Keep bundle size small — conditionally load JS per page216217Fetch the Stencil documentation and theme object reference for exact helper syntax, front matter keys, and object structure before implementing.