> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Installing Stencil CLI

> **Note**
>
> BigCommerce is currently sunsetting its node-sass fork in favor of the latest [sass/node-sass](https://github.com/sass/node-sass). To ensure that your storefront is up to date, use the latest active or maintenance node version in Stencil CLI and use the CLI command to resolve [incompatible SCSS directives](/developer/docs/storefront/stencil/cli/unexpected-behavior#incompatible-scss-directives), which can cause issues with the styling of your storefront. Your current production site will continue to function as designed, but all future updates will require you to address any SCSS compatibility issues with Node.js 24. This upgrade is necessary to ensure the security of our platform and that you are not running out-of-date packages that may expose your projects to additional security vulnerabilities.

Stencil CLI allows developers to locally edit and preview themes without impacting a merchant's live storefront, and its built-in [Browsersync](https://github.com/bigcommerce/browser-sync) 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.

### Requirements

* Python 3+
* Node.js 24+ (Stencil CLI supported version)

Note: If the Python version is more than 3.12, then you should install distutils using the following command:
`pip install setuptools`

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](https://github.com/bigcommerce/stencil-cli).

```shell showLineNumbers={false}

# Install Node Version Manager ([nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating) or any other version manager of your flavor)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Install Stencil CLI supported version of Node.js
nvm install 24

# Switch to Stencil CLI supported version of Node.js:
nvm use 24

# 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](https://chocolatey.org/install) to install Stencil CLI's dependencies. To do so, [open PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/starting-windows-powershell?view=powershell-6) as an administrator, and run the following commands:

```shell showLineNumbers={false}
# 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 24; nvm use 24

# Install Stencil CLI
npm install -g @bigcommerce/stencil-cli
```

> **Note**
>
> #### Execution policy errors
>
> If you receive an execution policy error while attempting to install chocolatey, refer to [Microsoft's Documentation](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-6) and/or consult with your organization's system administrator to determine the appropriate course of action.

> **Note**
>
> #### Chocolatey installation alternatives
>
> For additional information on installing Chocolatey and alternative installation options, see [the installation page on chocolatey.org](https://chocolatey.org/install).

### 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](https://git-scm.com/downloads) - required to run npm install
* [Node.js 24+ and npm](https://nodejs.org/en/download/releases/)

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

```shell showLineNumbers={false}
npm install -g @bigcommerce/stencil-cli
```

> **Note**
>
> These instructions have been tested successfully on **Windows 10**.
> Refer to [Stencil CLI README.MD](https://github.com/bigcommerce/stencil-cli) for latest `node` version supported.

## Installing on Linux

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

```shell showLineNumbers={false}
# 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 24

nvm use 24

# Install stencil
npm install -g @bigcommerce/stencil-cli
```

> **Note**
>
> * These instructions have been tested on **Ubuntu 18.04**.
> * Refer to [Stencil CLI README.MD](https://github.com/bigcommerce/stencil-cli) for latest `node` version supported.
> * Refer to [nvm](https://github.com/nvm-sh/nvm) for latest `nvm` install instructions.

## 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](/developer/docs/storefront/stencil/cli/development-server). Here's the gist:

```shell showLineNumbers={false}
# 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.

```powershell showLineNumbers={false}
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](https://medium.com/bigcommerce-developer-blog/dockerizing-bigcommerces-stencil-cli-f508ddc0c3c0) (medium.com)