Transitioning to Stencil

Whether you are new to Stencil or approaching Stencil from a different platform or theming framework (such as BigCommerce’s Legacy Blueprint), there are a few ways to develop a custom theme for your BigCommerce Stencil storefront. This article will provide instruction on how to transition to Stencil depending on your skill set, budget, and approach to the framework.

Find an Agency Partner

If you prefer an expert customize your theme, we recommend working with one of our certified certified BigCommerce Agency Partners. See our Partner Directory and Working with a Design Partner find an agency partner.

Adapt a Stencil Theme or Develop from Scratch

For complete control over a theme’s appearance and logic including the ability to edit all theme configuration files–you will want to use the Stencil Command-line interface, also known as the Stencil CLI.

Transition to Stencil from Blueprint

All new BigCommerce storefronts are powered by the Stencil theme engine. However, some BigCommerce stores still use our legacy theme framework, Blueprint. If you’re still using this legacy framework, consider switching to Stencil. Transitioning to Stencil allows developers to take advantage of new features, including Google Analytics Enhanced Ecommerce, Price Lists and Google AMP. Stencil also features a CLI that allows you to design and preview storefronts locally before pushing them to production. BigCommerce’s base Stencil theme, Cornerstone, is also natively mobile responsive.

Technical Differences

PHP vs Handlebars

Dynamic BigCommerce store data in Stencil themes are represented by Handlebars.js, a Javascript templating language. Dynamic content was previously represented by PHP variables enclosed within %% markers.

For details on using Handlebars to surface objects in Stencil, see Stencil Technlogy Stack.

WebDav vs CLI

In Blueprint themes, users were able to add new files and assets to themes via WebDav. In Stencil, assets must be added to and bundled into the theme, or referenced from an external source.

Customizing checkout with Stencil

Stores created before March 2019 had the option to switch to One Page Checkout (for Developers). This gave developers access to an editable checkout file. Switching to Stencil won’t affect One Page Checkout (for Developers). However, you should consider switching to Optimized One Page Checkout, as One Page Checkout (for Developers) will eventually be deprecated for all stores. See The Complete Guide to Checkout Customization on BigCommerce (Developer Blog) for more information.

Updating a theme

As with Blueprint themes, Stencil themes can receive updates from theme developers. You can apply theme updates by going to the BigCommerce Control Panel. When in the control panel, navigate to StorefrontMy Themes, and click Update.

BigCommerce shares updates to Cornerstone in our Changelog ( so you can verify that updates don’t conflict with your customizations.

For more on theme updates and best practices for handling version control, view this guide:


How will this affect my store? Will I lose data?

No store data will be lost when you switch from Blueprint to Stencil. A store’s theme is the presentation layer that renders your store catalog. You will lose any information you’ve hard-coded into your previous Blueprint theme.

How can I retain assets from my Blueprint theme?

For images referenced from anywhere in your Blueprint file directory, you will need to move these assets to your Stencil theme and reference them appropriately. You can still reference assets from within the /content/ folder in WebDav or from an external source.

Can I work on a custom Stencil theme without disrupting my live store?

Yes. The Stencil CLI allows you to preview theme changes on your live store locally. The changes won’t be reflected on your live store until you publish them.

Can I still use developer checkout?

If your store was created before March 2019, you will still be able to use One Page Checkout (for Developers). Consider switching to Optimized One Page Checkout, as this legacy checkout will eventually be deprecated for all stores.

SEO Tips and Best Practices

Search-engine optimization (SEO) helps translate an elegant theme into a successful, high-conversion storefront. Because so many shoppers reach online stores through a search engine, a search-optimized site will be more visible–attracting more traffic.

Stencil is designed for high SEO performance. However, you will want to keep SEO in mind as you build out each theme and storefront. For guidelines, see the following BigCommerce support articles (which are a series of intermediate to advanced chapters in our Guide to SEO):

Interacting with the BigCommerce API

Interacting with the BigCommerce API BigCommerce’s growing API resources enable application developers to create private scripts or apps that support a single store, or to create public apps offered to multiple stores via BigCommerce’s App Marketplace.

As a theme developer, you can rely on apps to enhance your themes’ capabilities, and to extend or complement the storefront features built into the BigCommerce platform. Popular app areas include inventory management, email marketing, coupons, reviews, shipping, tax accounting, and security. For more information, see BigCommerce’s:

Partnering with BigCommerce

No formal business relationship is required to develop themes on the BigCommerce platform. However, consider applying to become a become a BigCommerce Agency Partner, to accelerate your development of new business and revenue. For details, see our:


Related Articles

Additional Resources