Transitioning to Stencil

This article outlines the key differences between Blueprint and Stencil for developers, agency partners, and anyone interested in Stencil's enhanced capabilities.

What is Stencil?

Stencil is BigCommerce’s latest theme framework engine. Launched in 2016, Stencil incorporates industry best practices in technology, design standards, and SEO. You can use the framework’s theme on mobile, tablet, and desktop browsers. Stencil also allows developers to build storefronts that engage shoppers and encourage checkouts on any device. All of BigCommerce’s new storefronts use Stencil.

If you are still using our legacy theme framework, Blueprint, we highly encourage switching to Stencil so you can take advantage of the new features and benefits. For more in-depth information about Stencil’s features, see the Stencil Theme Platform (opens in a new tab) page.

Why transition to Stencil?

Stencil improves the overall storefront experience for merchants and their customers. With enhancements in speed, security, and updates to your themes, this modern framework provides a more streamlined process for the everyday maintenance and tasks required to run a store.

Stencil themes are built on non-proprietary, open-source code to provide easier adoption and adaptation while providing greater flexibility and access for customization. In comparison, Blueprint is built on a rigid, proprietary codebase, making it difficult to tailor and extend theme functionality.

For more information on the enhanced capabilities of Stencil, see the Stencil vs. Legacy Blueprint (opens in a new tab) page.

Technical differences

When transitioning any store from Blueprint to Stencil, you should be aware of a few key differences. Transitioning to Stencil allows developers to do the following:

• Develop locally on Stencil CLI
• Use Handlebars instead of global variables
• Customize Page Builder mode
• Create custom templates

Developing locally on Stencil CLI

For complete control over a theme’s appearance, logic, and theme configuration files, developers can use the Stencil command line interface (Stencil CLI). This interface allows you to design and preview storefronts locally before pushing them to production. Access to real-time previews and testing across various devices is available via Browsersync (opens in a new tab), a browser testing assistant built into Stencil CLI.

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

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.

For more information on Stencil theme assets, see the Theme Assets page.

Using Handlebars

While PHP variables enclosed within %% markers represent dynamic content, Handlebars (opens in a new tab), a JavaScript templating language represents BigCommerce dynamic stored data in Stencil themes.

Handlebars keeps your HTML page clean by separating the logic-less templates from the business logic in your JavaScript files. This organization improves the structure of the application, promoting maintainability and scalability. Handlebars also simplifies the task of manually updating data in the customer-facing display view.

For more information about Handlebars, refer to these external resources:

• A Beginner’s Guide to Handlebars (opens in a new tab)
• Getting Started with Handlebars.js (opens in a new tab)
• Handlebars interactive tutorial (opens in a new tab)

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

Customize Page Builder mode

While Blueprint uses Style Editor to customize legacy themes, Stencil uses Page Builder. Page Builder (opens in a new tab) is BigCommerce's browser-based tool that enables merchants to rapidly modify and customize a storefront's look and feel without writing code. Stencil theme developers can configure settings for Page Builder. The configuration determines the theme's customizable aspects.

For example, by customizing the configuration of Page Builder, you can modify how merchants customize colors, fonts, display of page features, and the number of products displayed per feature.

When you switch to Stencil from Blueprint, you won’t lose any of your store data. However, you will lose any customization you’ve hardcoded into your previous Blueprint theme.

Create custom templates

Stencil allows theme developers and merchants to assign custom layout templates to the following types of storefront pages:

• Brand (unique to Stencil)
• Category
• Product
• Store (static page)

Unlike Blueprint, Stencil does not require that custom template file names start with an underscore. In the current Stencil release, you must create and bundle custom templates using Stencil CLI before uploading the custom templates to stores. However, once you have created and uploaded templates, authorized store users can assign them to storefront pages through the control panel. For more information on custom templates, see the Custom Templates page.

Resources

For more information about switching to Stencil, see the following resources:

• Getting Started with the Stencil Framework (opens in a new tab)
• Stencil Theme Editor (opens in a new tab)
• Editing Stencil Theme Files (opens in a new tab)
• Personalizing Your Stencil Theme (opens in a new tab)
• What to Consider When Changing Your Stencil Theme (opens in a new tab)