Installing Stencil CLI

Stencil CLI allows developers to locally edit and preview themes without impacting a merchant's live storefront, and its built-in Browsersync (opens in a new tab) capabilities make simultaneous testing across desktop, mobile, and tablet devices a breeze. Once work is complete, developers can push themes to BigCommerce storefronts and make them live using Stencil CLI's simple yet powerful commands.

This article contains detailed instructions on installing and configuring Stencil CLI, the first step towards developing Stencil themes for BigCommerce storefronts.

Installing on Mac

There are different options for installing Stencil CLI and its dependencies on a Mac.

Option 1: ARM based macs

To install Stencil CLI and its dependencies on Mac, open a terminal and run the following commands. For the latest node version supported, refer to Stencil CLI README.MD (opens in a new tab).

# For ARM based macs
arch -x86_64 /bin/zsh
 
# Install Node Version Manager (nvm)
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash
 
# Install Stencil CLI supported version of Node.js
nvm install 20.16.0
 
# Switch to Stencil CLI supported version of Node.js:
nvm use 20.16.0
 
# Install Stencil CLI
npm install -g @bigcommerce/stencil-cli

Option 2: Macs with M1 chip

Installing Stencil CLI and its dependencies on Macs that use Apple silicon, such as the M1 chip, requires Rosetta. Rosetta allows a Mac with Apple silicon to use apps built for a Mac with an Intel processor.

To open the Rosetta terminal:

1. Open Finder.
2. Go to Applications > Utilities > Terminal.
3. Right-click Terminal and select Get Info.
4. Check the Open using Rosetta checkbox.
5. Close the window and quit all terminal instances.
6. Start a new terminal, and install Rosetta if prompted.

Run the following commands:

# Install Stencil CLI supported version of Node.js
nvm install 20.16.0
 
# Switch to Stencil CLI supported version of Node.js
nvm use 20.16.0
 
# Install Stencil CLI
npm install -g @bigcommerce/stencil-cli

Installing on Windows

There are two methods for installing Stencil CLI and its dependencies on Windows.

Method 1: Install dependencies using Chocolatey

If you prefer a streamlined installation option, use the Chocolatey package manager (opens in a new tab) to install Stencil CLI's dependencies. To do so, open PowerShell (opens in a new tab) as an administrator, and run the following commands:

# Install Chocolatey
iex ((New-Object System.Net.WebClient).DownloadString("https://chocolatey.org/install.ps1"))
 
# Install git if you don't have it
choco install git
 
# Install nvm windows and stencil-compatible node.js
 
choco install nvm; nvm install 20.16.0; nvm use 20.16.0
 
# Install Stencil CLI
npm install -g @bigcommerce/stencil-cli

Method 2: Install dependencies manually

If you're a pro at installing and configuring Python and Node.js environments on Windows, feel free to install the required dependencies using your preferred method.

Required Dependencies:

• Git (opens in a new tab) - required to run npm install
• Node.js 20.16.0 and npm (opens in a new tab)

Once they're installed and configured, use npm to install Stencil CLI:

npm install -g @bigcommerce/stencil-cli

Installing on Linux

To install Stencil CLI and dependencies on debian-based distros, open a terminal and run the following commands:

# Download and install nvm if you don't have it.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.36.0/install.sh | bash
 
# Reload .bashrc so nvm command works
source ~/.bashrc
 
# Explicitly install and use supported node version
nvm install 20.16.0
 
nvm use 20.16.0
 
# Install stencil
npm install -g @bigcommerce/stencil-cli

Depending on the distro, you may also need to install:

• g++
• libsass (opens in a new tab)
• git

Live previewing a theme

Once you've installed Stencil CLI, the next step on the road to theme development is downloading a theme to edit and previewing live changes using Stencil CLI's powerful Browsersync functionality. For detailed instructions on doing so, see Live Previewing a Theme. Here's the gist:

# move into theme dir
cd ~/path/to/theme/dir
 
# install theme modules
npm install
 
# initialize a new .stencil config for the theme
stencil init
 
# serve a live, Browsersync enabled preview of the theme
stencil start

Troubleshooting

Chocolatey install error

If you receive an error installing Chocolatey, run the following command to enable scripts on your system.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Visual Studio not found error

Stencil CLI's dependencies no longer require Visual C++ build tools to compile.

If you receive the error "Could not find VS", update to the most current version of Stencil CLI and run it using the version of Node.js indicated in this article.

Python npm configuration error

Stencil CLI's dependencies no longer require Python to compile.

If you receive "Error: Could not find any Python installation to use", update to the most current version of Stencil CLI and run it using the version of Node.js indicated in this article.

Resources

• Dockerizing BigCommerce's Stencil CLI (opens in a new tab) (medium.com)