The Stencil CLI enables developers to locally develop and customize on any Stencil theme with no impact to a merchant’s live storefront during the development process. When developing locally, you will have access to real-time Browsersync preview and testing across desktop, mobile, and tablet devices/viewports. This article contains detailed instructions on installing Stencil CLI on Mac, Windows, and Linux.
You will need to have an authentication token to use the Stencil CLI. See Getting API Credentials in Authentication in our API Docs to learn how to obtain an API Token.
Each OS has different prerequisites. Be sure to check the correct tab in the Prerequisites by OS (Mac OS, Linux, or Windows) section before attempting installation.
Prerequisites by OS
Mac OS Prerequisites
These instructions have been tested on Mac OS X Yosemite. Dependencies for other platforms will be added upon further testing.
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash
Next, explicitly install a supported Node.js version, using this convention:
nvm install 8
Install Stencil CLI
In your terminal (git bash recommended for Windows), use
npm to install the Stencil CLI:
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
npmcommand’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
npmcommand 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).
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 Repo
In your terminal,
cd to the directory you would like to use for working on themes, then clone the cornerstone repo:
git clone git://github.com/bigcommerce/cornerstone.git
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 CLI JS Dependencies
Before we can start using Stencil, we need to install some
npm modules to leverage the Stencil event framework. To do so,
cd into the cornerstone repo and run
cd cornerstone # move into cornerstone repo you just cloned npm install # install dependencies with node package manager
Watch a brief demonstration of the Stencil installation and launch: