Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 28 ยท Stencil Themes

Stencil CLI and the Cornerstone Theme

Learn how a BigCommerce Stencil theme is organized, what stencil init, start, bundle and push do, and why Cornerstone is the base most themes start from.

Everything so far has been about APIs and apps. Now we turn to what shoppers actually see: the storefront theme. BigCommerce themes are built with Stencil, a framework made of three parts: the Handlebars template language for HTML, SCSS and JavaScript for styling and behavior, and a command-line tool, the Stencil CLI, that previews your work against a real store and uploads it when you are done.

This lesson gives you the map: how a theme is laid out on disk, what the four everyday CLI commands do, and why almost every project starts from Cornerstone, BigCommerce's open-source reference theme. The commands touch a real store, so they are read-only here. The runnable stand-ins are JavaScript programs that draw a theme's folder tree and check a bundle against a list of rules, so you can reason about structure without installing anything. The rules in the validator are our own simplified model; the real upload checks are made by the platform.

Why start from Cornerstone

You could write a theme from nothing, but you would then have to rebuild a huge amount of behavior: product pages with option selectors, faceted category pages, a cart, account pages, search, quick view, responsive navigation and accessibility. Cornerstone already contains all of that and is the theme BigCommerce itself builds on. It is open source, so the usual workflow is to copy it, then change templates, styles and settings until it looks like your brand. Keeping Cornerstone's structure also makes later updates and merges easier, because you can compare your theme with a newer Cornerstone release.

You will also see the word variations: one theme can ship several style presets (for example different color schemes and layouts) that merchants pick in the control panel. Variations are described in the theme's configuration, which Theme Settings, SCSS and JavaScript covers.

Anatomy of a theme

A Stencil theme is a folder. Names below follow Cornerstone; the main idea is that behavior is split by purpose:

TEXT
my-theme/
  assets/
    js/               page scripts and the app entry point
    scss/             Sass source, split into settings, components, pages
    img/  fonts/      static files
  lang/
    en.json           translation strings (one file per language)
  templates/
    layout/base.html  the outer page shell every page extends
    pages/            one template per page type (home, product, category, cart...)
    components/       partials reused by pages (cards, forms, navigation...)
  config.json         theme settings values and variations
  schema.json         how those settings appear in the Theme Editor
  package.json        name, version, build scripts, dependencies
  stencil.conf.cjs    build configuration for the CLI
  webpack.conf.js     JavaScript bundling rules
  .stencil            LOCAL file: store URL, token and port (never share it)

Two ideas are worth remembering. First, templates/pages decides which template renders for which kind of page, while templates/components holds the pieces they share. Second, config.json holds the values of theme settings and schema.json describes the form the merchant sees in the editor. The next lessons look at templates and the settings pair in depth.

flowchart TD
    B["layout/base.html<br/>(page shell)"] --> P["pages/product.html"]
    B --> C["pages/category.html"]
    P --> K1["components/product/..."]
    C --> K2["components/category/..."]
    K1 --> S["shared components<br/>(cards, buttons, forms)"]
    K2 --> S

Layouts wrap pages; pages are built from components.

The four everyday commands

The Stencil CLI is a Node.js package installed globally; check the current Cornerstone documentation for the Node version it supports, as described in Setting Up a Development Environment. Then these commands cover most of your day (read-only):

Terminal
npm install -g @bigcommerce/stencil-cli

stencil init     # asks for the store URL, an API token and a local port; writes .stencil
stencil start    # runs a local preview server with live reload against your store's real data
stencil bundle   # builds assets and packs the theme into a .zip file
stencil push     # bundles and uploads the theme to the store (optionally activating it)
  • stencil init connects the folder to a store. The token it asks for is an API credential with theme permissions: treat it like any other secret, and make sure .stencil is in .gitignore.
  • stencil start serves your templates locally, but the data (products, categories, cart, settings) comes from the real store. You edit a template or a SCSS file and the browser reloads. This is the loop where you spend most of your time. By default the preview opens on a local port such as 3000.
  • stencil bundle produces the zip that the platform understands. It compiles your JavaScript and styles first, and it leaves out things that do not belong in a theme (dependencies, local configuration and the like).
  • stencil push uploads the bundle to the store. You can choose to apply it to a specific channel and activate it, or upload it inactive and activate it later in the control panel. A store keeps a limited number of uploaded themes, so delete old ones.

Version your work with Git, and bump the theme's version in package.json before each upload so you can tell uploads apart in the control panel.

flowchart LR
    I["stencil init"] --> S["stencil start<br/>edit and preview"]
    S --> Bd["stencil bundle<br/>build and zip"]
    Bd --> Pu["stencil push<br/>upload"]
    Pu --> A["Activate in<br/>control panel"]
    S -.->|"repeat"| S

Initialize once, loop on start, then bundle and push to release.

Stand-in 1: draw the theme tree

Real folders are easy to browse in an editor, but it helps to practice reading a structure from a flat list of paths, which is also how zip files list their contents. This program turns paths into an indented tree. It is a stand-in for browsing your theme: nothing here talks to BigCommerce.

JS Draw a theme folder tree

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output makes the split obvious: three kinds of templates in one folder, a handful of settings and package files at the root, and static assets on their own.

Stand-in 2: validate a bundle

A bundle is just a zip, and the platform refuses a theme that is missing essential files. The validator below checks a list of bundle paths against a small rule set: required files must exist, forbidden files must not be present (secrets and dependencies must never ship), and the version must look like major.minor.patch. The rules are our simplified model of a good bundle; for the real requirements, rely on stencil bundle and the platform's responses.

JS Check a bundle against simple rules

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The bad bundle collects every kind of failure: missing files, a leaked token, shipped dependencies and a malformed version. In real work you rarely hand-build a zip, since stencil bundle assembles it, but the habit of checking what goes into an artifact before uploading it carries over to every deployment. Performance, Security and Launch returns to this in a pre-launch checklist.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does stencil start do?

    stencil start gives a fast edit-and-reload loop locally; only bundle and push release the theme.
  2. 2. Which file describes the form a merchant sees in the Theme Editor?

    schema.json defines the settings UI, while config.json holds the setting values and variations.
  3. 3. Why should .stencil never be committed or shipped?

    The file contains credentials. Add it to .gitignore and keep it out of bundles.
  4. 4. What is the main reason to begin from Cornerstone?

    Cornerstone is an open-source reference theme with the common pages and features in place.
  5. 5. Where do reusable pieces such as product cards usually live?

    Components are partials shared by multiple page templates.

Summary

  • Stencil themes combine Handlebars templates, SCSS, JavaScript and a CLI; Cornerstone is the open-source base most themes start from.
  • A theme folder splits into assets, lang, templates (layout, pages, components) and configuration files.
  • config.json holds setting values and variations; schema.json defines the editor form.
  • stencil init connects, start previews with live reload, bundle builds a zip and push uploads it.
  • Keep secrets such as .stencil out of Git and out of bundles, and check what you ship.

Next: Handlebars Templates, Helpers and Page Context