Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars Syntax and Helpers
Handlebars Helpers
Stencil Object Model
Stencil Objects

Configuring the Stencil Theme Editor

Configuration Files

Each theme contains two related JSON files of key-value pairs: config.json and schema.json. These files’ keys provide the following features:

Keys that you include in schema.json – together with their corresponding config.json default values – define the settings that merchants can customize through the Theme Editor graphical interface. Other config.json keys contain metadata about the theme, such as the theme’s name, version, and resource controls. Keys located under the config.json > variations object define variations of the theme. For example, a theme might have a “Light” variation and a “Bold” variation, each with different typography and colors. Each theme can include as many variations as you like. Keys located under both files’ settings objects define the theme’s look, feel, and functionality.

For documentation on the principal keys included in Stencil’s reference Cornerstone theme, see this section’s config.json Metadata and schema.json Metadata entries. For an introduction to the graphical editor, see Stencil Theme Editor Overview.

Managing Keys between Versions

To make sure revisions to your theme are backward-compatibile, we generally recommend that you manage keys in both your config.json and schema.json files in an additive way. Specific recommendations:

Adding new keys is generally fine. (However, each key in schema.json must have a matching default in config.json.)

  • Use caution in deleting any key. Doing so can break your new theme version’s backward compatibility.
  • We do not recommend renaming keys. Instead, we recommend introducing a new key, while maintaining the old key until it is no longer in use by anyone using an older version of your theme.
  • Each object within your config.json > variations object defines one theme variation. If you are adapting an existing theme and consciously want to remove one or more variations, you can do so by removing the corresponding key(s).

Persistent Settings Storage

When store administrators use Theme Editor to customize your theme for their store, the store’s resulting configuration settings are saved to a separate configuration service at BigCommerce.

Theme Upgrades and Settings

When a merchant upgrades your theme to a newer version, all key-value pairs that were saved to the BigCommerce configuration service are carried forward. For example, assume this customization/upgrade scenario:

You release your Star Glow theme, version 1. This theme’s config.json includes a key named logo_size, establishing a default value of 100x250. The combination of the key and the value compose a logo_size setting. The merchant uses Theme Editor to change the logo_size setting to 175x275. This customized setting is stored in the BigCommerce configuration service. You release Star Glow, version 1.1. In this theme revision, you have changed the logo_size to 300x300. When the merchant applies Star Glow version 1.1 to their store, their custom logo_size setting of 175x275 remains in effect. If you the merchant creates a second store and applies Star Glow version 1.1 to it, that store has no custom logo_size setting – so it will default to the new theme version’s 300x300 value.