Loading tutorials…
Loading tutorials…
Stencil is BigCommerce's theme framework — Handlebars templates + SCSS + a build pipeline. Most owners customize via the Theme Editor and hit a wall. The Stencil CLI unlocks real customization but has a 4-6 hour learning curve. Here's the full path.
Who this is forBigCommerce owners or in-house developers who need customizations beyond what the Theme Editor allows: custom homepage sections, new template variants, brand-specific component design. Required for stores doing $100K+/mo who want a unique storefront.
What you'll need
Step 1
npm install -g @bigcommerce/stencil-cli. Generate a stencil-cli API token in BigCommerce admin. Authenticate with stencil init.
Open terminal. Confirm Node.js: node --version (must be 18+, ideally 20+).
Install Stencil CLI globally: npm install -g @bigcommerce/stencil-cli. Verify with stencil --version.
BigCommerce admin → Settings (top right gear) → API → API Accounts → "Create API Account." Name "Stencil CLI" (or similar). OAuth scopes: at minimum "Themes" (modify). Save and copy the access token (shown once).
Create a working directory: mkdir my-store-theme && cd my-store-theme.
Download the production theme: BigCommerce admin → Storefront → Themes → click the active theme → "Advanced" dropdown → "Download Theme Files." Unzip into your working directory.
Run stencil init in the theme directory. Enter your store URL and the API token. This creates a .stencil config file with auth + store metadata.
Step 2
Run 'stencil start' in the theme directory. Opens a local preview server (default localhost:3000) that proxies live store data through your local templates.
In the theme directory: stencil start.
Stencil downloads the latest theme schema, builds SCSS, and starts a local server. Default URL: localhost:3000 (port can change if 3000 is taken).
Open localhost:3000. You see your live store, but rendered through your local theme files. Edit a Handlebars template (e.g., templates/pages/home.html) or SCSS file (e.g., assets/scss/theme.scss) → save → the preview auto-reloads.
This is the development loop: edit local → see in browser → iterate. NO changes are pushed to production yet.
Critical: 'stencil start' uses LIVE store data (products, prices, inventory) but your local templates. Test customer-facing changes carefully — what you see is what real customers would see if you pushed to production.
Step 3
Edit templates/ for HTML layout, assets/scss/ for styles. Use schema.json to expose new options to the Theme Editor for non-developer changes.
Templates: templates/components/ (reusable components), templates/pages/ (page-specific layouts), templates/layout/ (overall site shell — base.html). Handlebars syntax: {{variable}}, {{#each items}}{{/each}}, {{> partial}}.
Styles: assets/scss/ uses Sass. theme.scss is the main entry. Component-specific styles in assets/scss/components/. Avoid editing assets/scss/_global.scss directly — it gets overwritten on theme updates.
New homepage section: open templates/pages/home.html. Add a new partial reference: {{> components/custom-banner}}. Create the partial at templates/components/custom-banner.html with your HTML + Handlebars.
Expose to Theme Editor: schema.json defines what shows in the visual editor. Add a new section with fields (text, image, color) so non-developers can edit the new component via the Theme Editor.
Don't edit core Cornerstone components in place (header.html, footer.html, product-view.html). Instead: copy to a renamed partial and reference your copy. This makes BigCommerce Cornerstone updates upgrade-safe.
Step 4
schema.json + config.json: schema defines editable settings. config.json holds the values. The Theme Editor renders schema as a visual UI.
Open config.json (theme defaults) and schema.json (editable controls definition).
To add a new Theme Editor control: in schema.json, add a new section with fields like { "type": "text", "name": "hero_headline", "label": "Hero Headline", "default": "Welcome" }.
In your Handlebars template, reference: {{theme_settings.hero_headline}}. The value shows whatever the merchant set in the Theme Editor.
For images: { "type": "imageManager", "name": "hero_image", "label": "Hero Image" } — opens BigCommerce Image Manager picker.
For colors: { "type": "color", "name": "accent_color", "label": "Accent Color", "default": "#000000" } — color picker.
After updating schema, run stencil start, refresh the Theme Editor (admin → Storefront → My Themes → your theme → Customize) — new controls appear in the sidebar.
Step 5
Run 'stencil bundle' to package the theme. 'stencil push' uploads. Apply via admin (or stencil push --activate).
In the theme directory: stencil bundle. Stencil validates the theme (template syntax, schema validity, file sizes) and produces a .zip file.
If validation fails, fix errors and re-bundle. Common errors: missing required schema fields, oversized images, invalid Handlebars syntax.
stencil push: uploads the bundled theme to BigCommerce. Adds it to your theme library but does NOT activate. The theme appears in admin → Storefront → My Themes.
In admin → My Themes → click the uploaded theme → "Apply" → BigCommerce activates it. The new theme is live within 60 seconds.
Alternative: stencil push --activate uploads + activates in one command. Use only after validating on a staging variant.
For safety: keep one "Production" theme and one "Staging" theme. Push customizations to Staging first, validate end-to-end, then push to Production.
Step 6
A single theme can have multiple Variants (e.g., "Default," "Holiday," "Black Friday"). Apply different variants without re-uploading.
In schema.json, define multiple variants under "variants" array. Each variant overrides specific settings (e.g., colors, layout choices).
BigCommerce admin → My Themes → click theme → see variants list. "Apply" any variant — site updates within seconds.
Use case: Black Friday color scheme. Build a Holiday variant with red+black theme. Apply on launch day. Apply Default back on Dec 1. No code deployment needed.
Use case: A/B testing layout. Build two variants with different homepage hero sections. Apply variant A for one week, variant B the next. Measure CR per variant.
Variants are NOT a substitute for proper staging. Validate the variant locally with stencil start --variation MyVariant before applying live.
Step 7
Commit theme files to Git. Use a deployment script that runs stencil bundle + stencil push on merge to main. Avoid manual uploads for team workflows.
In the theme directory: git init. Add a .gitignore that excludes .stencil/, node_modules/, and any .zip files.
Commit theme files to a private repo (GitHub, GitLab, Bitbucket). One developer == one source of truth.
For team workflows: configure GitHub Actions / GitLab CI to run "stencil bundle && stencil push" on merge to main. Requires: BigCommerce API token in CI secrets.
Branch strategy: main = production-deployed, develop = staging-deployed. Pull Requests against develop. Approved PRs auto-deploy to BigCommerce staging variant. Merges to main auto-deploy to production after manual approval.
Without version control, multiple developers overwriting each other within a week is normal. Theme code is real code; treat it like real code.
Common mistakes
Editing core Cornerstone templates directly
What goes wrong: Every Cornerstone update (BigCommerce ships updates every few months) requires manually merging your changes into the new version. After 2-3 updates, the theme is in permanent merge-conflict hell. Time to update goes from 1 hour to 1 week.
How to avoid: Extend via custom partials (copy header.html → custom-header.html, reference custom-header from your layout). Never edit core templates in place.
No schema for editable settings
What goes wrong: Hardcoded copy, colors, and images in templates. Every text change requires a developer + a redeploy. Marketing team waits 2 weeks for a copy tweak. Trust between dev + marketing erodes.
How to avoid: Expose every "merchant might change this" string as a schema field. Theme Editor renders the UI. Marketing changes copy without dev help.
No version control on theme code
What goes wrong: Multiple developers manually edit and stencil push. Each overwrites the others. After 30 days, no one knows what the current source-of-truth code looks like. Bugs reappear that were 'fixed' last month.
How to avoid: Git init. Commit theme code. Define a deployment workflow (manual or CI/CD). Treat theme code like application code.
Pushing untested code to production
What goes wrong: Direct stencil push --activate to production. A typo in product-view.html breaks every product page for 30 minutes before someone notices.
How to avoid: Always push to a staging variant first. Validate end-to-end (home, product, category, cart, checkout). Then promote to production.
Ignoring the schema validation in stencil bundle
What goes wrong: Bundle warnings ignored. Theme uploads but breaks on certain Theme Editor pages. Merchant changes a setting and the page 500-errors.
How to avoid: stencil bundle output should be clean (no warnings). Fix every warning before pushing. They are warnings for a reason.
Building features that should be in apps, not the theme
What goes wrong: Custom upsell logic, loyalty rules, abandoned cart messaging all hardcoded into the theme. Theme bloats. Migrating to a new theme means re-implementing all of it.
How to avoid: Use BigCommerce apps for business logic (upsells, loyalty, abandoned cart). Themes are for layout + design. Keep the line clean.
Recap
Done — what's next
How to set up a BigCommerce store from scratch
Read the next tutorial
Hand it off
Stencil is genuinely powerful and has a real learning curve. A vetted BigCommerce developer with Stencil experience can set up a clean custom theme baseline (with schema, version control, deploy workflow) in 1-2 weeks at $14-16/hr — typically $600-1,500 for a clean baseline, $300-600/mo for ongoing theme work.
See specialist rates
Not for basic changes — the Theme Editor handles colors, logo, fonts, layout toggles, and Page Builder widgets. Stencil CLI is required for: custom templates, custom Handlebars partials, custom SCSS components, new schema fields. About 80% of stores never need Stencil CLI.
Stencil is the underlying theme framework (templates + SCSS + build tools). Theme Editor and Page Builder are visual UIs ON TOP of Stencil, exposing settings defined in the theme's schema.json. Page Builder widgets are also Stencil components — just pre-built ones from BigCommerce.
Almost always extend Cornerstone (or a paid theme). Building from scratch means re-implementing thousands of lines of e-commerce templating (cart, checkout, product variants, search). Even a 'fully custom' theme typically extends a base — extending Cornerstone saves 80-120 hours.
Yes for specific widgets — mount React components on specific DOM nodes via the theme's JS bundle. But for full headless: use the BigCommerce Storefront API + a Next.js / Nuxt frontend. Hybrid (Stencil shell + React widgets) is a common middle ground.
Paid themes ($150-300 one-time from the Theme Marketplace) typically have better default layouts for specific verticals (apparel, electronics, B2B), more design polish, and more pre-built Page Builder widgets. Code quality varies — some paid themes are well-maintained, others are abandoned 6 months after purchase. Buy from theme authors with recent updates.
Yes. Themes are visual layer only. Products, customers, orders, settings all persist when you switch themes. What you lose: theme-specific settings (logo upload, color choices, Page Builder layouts) — they don't carry to the new theme.
BigCommerce
Most new BigCommerce stores go live with broken tax rules, missing shipping zones, and unverified payment flows. Then the first 30 orders surface every gap one customer at a time. Here's the systematic setup that catches these before launch.
BigCommerce
BigCommerce has cleaner SEO defaults than WooCommerce and rivals Shopify on most factors — but the platform leaves four to five high-impact SEO settings unset by default. Fixing them is usually the difference between 'page 3' and 'page 1' on product searches.
Shopify
Shopify killed checkout.liquid in August 2025. If you haven't migrated, your old pixels and order-confirmation customizations are silently broken. Here's the full checkout extensibility migration — pixels, CAPI, and post-purchase logic.