> 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.

# Lab - Getting Started with the Stencil CLI

Plan: Developer Foundations

Lesson 4 of 16 · 30 min

Developing a custom Stencil theme usually starts with cloning the official default theme, Cornerstone. To develop effectively in a local environment, you'll use the Node.js-based Stencil CLI tool to run a local server, connecting your custom theme code to your BigCommerce store data.

**In this lab, you will:**

* Create an API account for Stencil
* (Optional) Enable Makeswift
* Clone the Cornerstone theme
* Install Stencil CLI
* Connect your local theme files to your BigCommerce store
* Run a local dev server

**Prerequisites**

To successfully complete this tutorial, you will need the following:

* A BigCommerce store admin user with the "Create store-level API accounts" permission
* Node.js 20 or later
* The [Git](https://git-scm.com/) CLI
* A command-line interface on your local machine

> **Info**
>
> [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) is an alternative way to install Node.js and allows you to install and use different versions.
>
> With nvm installed, you can install a specific version:
>
> `nvm install 20`
>
> ... and switch to the Node.js runtime of any version you have installed:
>
> `nvm use 20`
>
> Whether you use nvm or install Node.js via another method, make sure you are running a compatible version:
>
> `node -v`

## Step 1: Create an API Account

1. In the BigCommerce control panel, **navigate** to Settings > API > Store-level API accounts.
2. **Click** "Create API account" and **select** "Stencil CLI token" as the token type.
3. **Enter** a name for the account.
4. **Select** "publish theme" as the Stencil CLI access level.

> **Info**
>
> You'll use this API account in a later lab to bundle and publish your theme. For proper access control, you should create a separate account with the "local development only" access level for any team members who should have permission to develop on the theme but not upload it.

5. **Save** the account and **record** the access token that is displayed in the resulting modal.

## Step 2: Optional: Enable Makeswift

For users wanting to explore the capabilities of the Makeswift editor, you can opt in from the control panel and provision a Makeswift site for your Stencil storefront.

> **Warning**
>
> Makeswift for Stencil is currently in beta. Features and availability are subject to change.

1. In the BigCommerce control panel, **navigate** to Channel Manager.
2. **Select** your Stencil storefront channel to open its channel entry.
3. **Opt in** to Makeswift for the channel.
4. **Click** "Edit in Makeswift". The first time you open the editor, BigCommerce provisions a Makeswift site for your channel, which may take a moment.

Once provisioning completes, the Makeswift editor opens with a live preview of your storefront. You can return to it at any time using the "Edit in Makeswift" button on the channel entry.

## Step 3: Install Stencil CLI

This step only needs to be performed once for a specific version of Node.js.

1. **Run** the following command to install the Stencil CLI tool.

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

> **Info**
>
> Remember to make sure you have Node.js 20 or later running before installing the package. If you're using Node Version Manager:
>
> `nvm use 20`

The command will install the *stencil-cli* package globally. This will allow you to use it in multiple Stencil theme projects using the same version of Node.js.

> **Info**
>
> **ARM Based Macs**
>
> For ARM based Macs, you will need to run the following before installing the package:
>
> `arch -x86_64 /bin/zsh`

> **Info**
>
> **Installing Dependencies on Windows**
>
> See the [BigCommerce documentation](/developer/docs/storefront/stencil/cli/install) for more details on options for installing dependencies on Windows before installing the Stencil CLI package.

2. **Test** the *stencil* command and **verify** that a list of possible sub-commands is output.

```bash showLineNumbers={false}
stencil -h
```

## Step 4: Clone the Cornerstone Theme

1. **Run** the following command to clone the Cornerstone default theme from [GitHub](https://github.com/bigcommerce/cornerstone/) to a local location.

```bash showLineNumbers={false}
git clone https://github.com/bigcommerce/cornerstone.git
```

2. **Install** *npm* dependencies.

```bash showLineNumbers={false}
cd /path/to/theme
npm install
```

You should now have a complete copy of the Cornerstone theme source files, with dependencies installed in the *node\_modules* directory.

## Step 5: Initialize Stencil

This step only needs to be performed once for a given Stencil theme project locally.

You'll need the access token you recorded after creating the API account in your control panel.

1. In your theme working directory, **run** the following command.

```bash showLineNumbers={false}
stencil init --url <store_url> --token <access_token> --port 3000 --packageManager npm
```

This *init* command will generate a configuration file connecting your local theme package with your store.

* Replace **\<store\_url>** with the fully qualified URL of your Stencil storefront (for example, "https\://\<store-name>.mybigcommerce.com").
* Replace **\<access\_token>** with your recorded access token.
* The **--port** option specifies the local port the server will run on (for example, *localhost:3000*).
* The **--packageManager** option specifies which package manager to use for dependencies.

> **Info**
>
> You may also choose to run the command with no options:
>
> `stencil init`
>
> This will result in interactive prompts allowing you to provide appropriate values.

2. **Verify** that the file *config.stencil.json* has been generated in your main theme directory.

## Step 6: Start the Live Preview

1. In your theme working directory, **run** the following command to start a local dev server with a live preview of your theme.

```bash showLineNumbers={false}
stencil start
```

2. If necessary, **choose** a storefront to run from the interactive prompt.

After the dev server starts, you should see output printing the local URL(s) you can use to access the preview.

![Stencil URLs](/_fern-files/bigcommerce.docs.buildwithfern.com/2cf938cd3a44b832035f72556ad00ea9f870fb7d6bfa873605c2624a3a15170a/assets/learn/storefront-foundations/stencil-start.png)

3. **Browse** to the main "Local" access URL printed in the output. This should be `http://localhost:3000` if you used the 3000 port in the *init* command. **Verify** that your storefront is loaded in the browser.

![Example storefront loaded in live preview](/_fern-img/7830cd2941d39d96b24edec643fd2f433dbcb0689ef3def233ad9d34752541c4.webp)

You should leave the dev server process running in your terminal as you customize and preview your theme. When you're ready to stop the server, simply cancel the process (Ctrl+C).

Run `stencil start` from within your theme directory at any time to restart the dev server.