> 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

Plan: Stencil Developer

Lesson 3 of 18 · 30 min

**In this lab, you will:**

* Create an API account
* (Optional) Enable the Makeswift editor for your channel
* Install dependencies for your operating system
* Install Stencil CLI
* Clone the Cornerstone theme from GitHub
* Initialize and launch Stencil CLI
* View customized changes locally on localhost:3000

**Prerequisites**

* Owner permissions within a live/test BigCommerce Store (required for API credential creation)
* Admin permission on your computer
* Basic knowledge of HTML, Sass, and Handlebars
* Node.js 20 or later
* The [Git](https://git-scm.com/) CLI

> **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`

## Authentication

Two types of API credentials are available to developers wishing to make requests against BigCommerce APIs.

These credentials are used to programmatically interact with an individual store's data using BigCommerce's APIs. The two types of API credentials are:

* **Store API Credentials** (created in a store's control panel)
* **App API Credentials** (created in the Developer Portal)

In this course, we focus on the Store API credentials. Both OAuth and token-based authentication are possible with Store API Credentials. Store API Credentials are generated when a Store API Account is created in a store's control panel: Settings > API.

Access to API keys depends on user permissions set by the store owner. If you do not have access to API keys, ask the store owner to change your user permissions in the control panel.

When setting the theme scope to modify, note the difference between read-only and modify:

| **Read-only**                                                      | **Modify**                                                                                                                                        |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read-only lets you connect so you can use the browsersync preview. | Modify lets you push a theme to a store using the command line, instead of having to bundle it and upload the zip file through the control panel. |

![Click to enlarge image](/_fern-img/8725d41d47ae9bf59007ee7039cf0dac29cfcbda1878f9bd4c44588a58446d1c.webp)

### API Path

A successful save will display a pop-up containing the API credentials you need to run authenticated requests - your **Client ID** and **Access Token**. A .txt file containing the same credentials will (on most browsers) automatically download to your computer. This file contains the base API Path for your store, preconfigured for the v3 API.

The base API path will look something like the image to the right.

> **Info**
>
> Make sure to keep your API credentials in a safe place as you will no longer be able to access them from the BigCommerce control panel.

## Step 1: Create an API Account

1. **Log in** to the store you will be developing on
2. **Navigate** to Settings > API Accounts
3. **Click** Create API account and **select** Create Stencil-CLI Token

> **Info**
>
> Access to API keys depends on user permissions set by the store owner. If you do not have access to API keys, ask the store owner to change your user permissions in the control panel.

4. **Add** a Name
5. **Set** the Stencil-CLI Access Level to Publish Theme

> **Info**
>
> When setting the theme scope to publish theme, note the difference between local development only and publish theme:

| **Local Development Only**                             | **Publish Theme**                                                        |
| ------------------------------------------------------ | ------------------------------------------------------------------------ |
| Can read theme-related store data, but can not publish | Can read theme-related store data and push themes to the live storefront |

6. **Click** Save

## Step 2: (Optional) Enable Makeswift

For users wanting to explore the capabilities of the Makeswift editor, follow these instructions to enable Makeswift on your channel and provision a Makeswift site. If you only want to work with the Stencil CLI, you can skip this step.

> **Warning**
>
> Makeswift for Stencil is a Beta feature. Functionality and control panel steps may change, and it should not be relied on for production stores.

1. **Log in** to the control panel of the store you are developing on
2. **Navigate** to Channel Manager
3. **Select** the storefront channel you are developing on
4. **Opt in** to Makeswift for the channel when prompted to enable the visual editor

Once Makeswift is enabled for the channel, provision your Makeswift site:

5. **Return** to the channel's entry in Channel Manager
6. **Click** Edit in Makeswift

The first time you click **Edit in Makeswift**, BigCommerce provisions a Makeswift site for the channel and opens the Makeswift editor. From here you can visually edit pages built on your Stencil theme. For more detail, see [Makeswift on Stencil](https://docs.makeswift.com/product/docs/guides/makeswift-on-stencil).

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

> **Info**
>
> Versions are subject to change; ensure you are using a supported Node version. If you are experiencing issues, review our Developer Documentation on [Troubleshooting Your Setup](/developer/docs/storefront/stencil/cli/unexpected-behavior).

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. **Use** the following command to clone the base theme into your chosen directory

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

> **Info**
>
> If the above command fails and you are accessing GitHub anonymously, give the URL the `git` prefix:
>
> `git clone git://github.com/bigcommerce/cornerstone.git`

2. **Use** the following command to move into the theme directory

```bash showLineNumbers={false}
cd ~/Cornerstone
```

> **Info**
>
> A folder called "Cornerstone" was automatically downloaded in step 1. If you created a specific folder for this project you will need to call up the path to the folder.
>
> ex. The Cornerstone theme was cloned to a folder called "Development".
>
> `cd ~/Development/Cornerstone`

3. **Navigate** **to** the theme directory (Cornerstone) and **run** the following command to install Stencil's JavaScript dependencies

```bash showLineNumbers={false}
npm install
```

## Step 5: Initialize and Launch Stencil CLI

1. **Use** the following command in the theme directory

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

2. **Enter** the website URL (ie. `https://websiteurl.com)` for the theme you are developing for
3. **Enter** the port you would like to run the store on (we recommend the default 3000)
4. **Enter** your Access Token
5. **Observe** confirmation that Stencil is initialized
6. **Use** the command below in the theme directory to launch the CLI

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

7. **Observe** the list of URLs to access the local store
8. **Navigate** to the store (ex. localhost:3000)

![Example: Initialize and Launch Stencil CLI](/_fern-img/f528911bae8a62365991dbf17f26250353ef12b92a4330f3f788b7f3903a17c7.webp)

> **Info**
>
> **Quickstart Command**
>
> The quickstart command produced by the control panel is "stencil init" with the -p -t and -u options to define the port, token, and URL respectively.
>
> For example:
>
> `stencil init -p 3000 -t <API_TOKEN> -u https://my-cool-store.mybigcommerce.com`

> **Info**
>
> If you encounter any issues, view the Stencil Documentation [Troubleshooting Your Setup](/developer/docs/storefront/stencil/cli/unexpected-behavior).

## Resources

* [Stencil CLI Installation Dependencies](/developer/docs/storefront/stencil/cli/install)
* [NVM Installation](https://github.com/nvm-sh/nvm#installation)
* [Current Node Version](https://github.com/bigcommerce/stencil-cli?tab=readme-ov-file#install)
* [Troubleshooting Stencil CLI](/developer/docs/storefront/stencil/cli/unexpected-behavior)
* [Cornerstone Repository](https://github.com/bigcommerce/cornerstone)