Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars and Stencil
Handlebars Helpers
Stencil Object Model
Stencil Objects

Installing Stencil

Below you’ll find instructions on installing the Stencil CLI, cloning the Cornerstone theme, and installing Stencil’s Javascript utilities. Each OS has different prerequisites, so check the Prerequisites by OS section before attempting installation.

Video Demo

Watch a brief demonstration of the Stencil installation and launch:

Stencil Prerequisites by OS

Mac OS Prerequisites

Platform Support

These instructions have been tested on Mac OS X Yosemite. Dependencies for other platforms will be added upon further testing.

Installing Xcode

You must install the Xcode development tools (latest stable version).


Stencil requires the Node.js runtime environment, version 6.x or later. We have tested Stencil on selected Node.js versions, from 6.10.3 to 7.9.0.

We recommend that you install or update Node.js using nvm. First install nvm, version 0.31.0, as follows:

curl -o- | bash

Next, explicitly install a supported Node.js version, using this convention:

nvm install 6.4.0
Notes on Dependencies

You can choose to instead download the latest x.x version of Node.js from the Node.js Foundation’s archives, using URLs of the form:,, etc. We recommend installing only LTS (“Long-Term Support”/“Mature and Dependable”) versions.


If you run into any problems with Stencil installation or launch, first consult Troubleshooting Your Setup.

If that does not resolve your issue, consult our Support resources, which include community and peer support via BigCommerce and Stack Overflow forums.

Installing the Stencil Command Line Interface

The first step toward developing on Stencil is to install the Stencil CLI.

You can do this via the following command (If you are using Windows, you will need to run this command in git bash.):

npm install -g @bigcommerce/stencil-cli

Items to Note

  • The command above requires npm to be installed in your local development environment.

  • In Windows, this npm command’s execution might at times appear to freeze. However, the installer is running. Give it several minutes to complete installation.

  • On Mac OS machines with installed xcode, version 5.x, this npm command has generated errors of the form: npm ERR! invalid: string_decoder. The workaround is to upgrade xcode to the latest stable xcode version (7.3.1 as of this page’s last revision).

  • If you receive a file-permissions error, and you did not install Node.js via nvm (Node Version Manager), then either install nvm now, or follow one of the workarounds on this external page.

CLI Force Upgrade and Cornerstone 2.0.0

To ensure the Stencil CLI is compatible with all the changes introduced in Cornerstone 2.0.0, you must upgrade to the latest version of Stencil CLI (1.15.1) if using Cornerstone 2.x.x.

Occasionally, you will receive a command line prompt to run the installation command when you restart your Stencil server. This occurs when BigCommerce publishes a critical fix in Stencil CLI, to resolve an issue like a newly discovered security exploit.

Cloning Cornerstone using Github

Windows users need to run this in git bash.

Navigate to a directory where you would like to install a subdirectory for your theme. You must have appropriate write permissions in this directory.

Execute the following command to clone Stencil’s base theme, Cornerstone, into a new subdirectory named /cornerstone/

git clone

If the above command fails, and you are accessing GitHub anonymously, give the URL this alternate prefix:

git clone git://

In the next step, you will install Stencil’s JavaScript utilities to enable API access via Ajax.

Back Up before Reinstalling

If you are reinstalling over a base theme on which you have already begun development, first back up your theme’s .stencil file. This contains your store URL, BigCommerce username and access tokens, and other basic settings. Preserving those settings will speed up initializing and launching the new version. If you would like to allow for complete rollback, back up your entire theme’s directory.

Installing Stencil’s Javascript Dependencies

Windows users need to run this in git bash.

Complete the following steps:

Navigate to your Stencil theme directory. This example assumes that this target directory has the default name cornerstone.

cd cornerstone

Next, execute the following command inside of that directory:

npm install

This will install the required npm modules to properly leverage the Stencil event framework.

Now that your installation is complete, you can move on to preparing your store/tokens