Installing Stencil CLI
BigCommerce is currently targeting 01/31/2024 to sunset its node-sass fork in favor of the latest sass/node-sass (opens in a new tab). To ensure that your storefront is up to date, use the latest node version (Node 18) in Stencil CLI and use the CLI command to resolve incompatible SCSS directives, which can cause issues with the styling of your storefront.
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.
To install Stencil CLI and its dependencies on Mac, open a terminal and run the following commands. Refer to Stencil CLI README.MD (opens in a new tab) for latest
node version supported.
These instructions have been tested on Mac OS X Yosemite.
# 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 18.15.0 # Switch to Stencil CLI supported version of Node.js: nvm use 18.15.0 # Install Stencil CLI npm install -g @bigcommerce/stencil-cli
There are two methods for installing Stencil CLI and its dependencies on Windows.
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 18.15.0; nvm use 18.15.0 # Install Stencil CLI npm install -g @bigcommerce/stencil-cli
If you receive an execution policy error while attempting to install chocolatey, refer to Microsoft's Documentation (opens in a new tab) and/or consult with your organization's system administrator to determine the appropriate course of action.
For additional information on installing Chocolatey and alternative installation options, see the installation page on chocolatey.org (opens in a new tab).
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.
Once they're installed and configured, use
npm to install Stencil CLI:
npm install -g @bigcommerce/stencil-cli
These instructions have been tested successfully on Windows 10.
Refer to Stencil CLI README.MD (opens in a new tab) for latest
node version supported.
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 18.15.0 nvm use 18.15.0 # Install stencil npm install -g @bigcommerce/stencil-cli
Depending on the distro, you may also need to install:
- libsass (opens in a new tab)
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
If you receive an error installing Chocolatey, run the following command to enable scripts on your system.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
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.
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.