Configuring the Stencil Theme Editor
Each theme contains two related JSON files of key-value pairs:
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.
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
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
- 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
variationsobject 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
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.