bc-stencil

BigCommerce Stencil Theme Development

Before writing code

Fetch live docs:

1. Fetch https://docs.bigcommerce.com/developer/docs/storefront/stencil/overview for Stencil overview
2. Fetch https://docs.bigcommerce.com/developer/docs/storefront/stencil/themes/context/object-reference/elements for theme object reference
3. 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:

1. Template files (Handlebars .html) define page structure
2. Front matter (YAML) at the top of each template declares what data to fetch
3. BigCommerce injects theme objects (product, category, cart, settings, etc.) into the template context
4. Handlebars helpers and partials render the data
5. SCSS compiles to CSS, JS bundles with webpack
6. 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}}
---