Stencil CLI Setup for BigCommerce Theme Development

1. This is how you install Stencil CLI on Mac. The BigCommerce Dev Center resource is close to being correct, but I had some issues installing NVM. I think the resource instructs you to install an old version. On the NVM Github page they have a new version, so I ran the new version instead.

2. Installation instructions are below. Please note how I label “BIGCOMMERCE INSTRUCTION” vs. “MY METHOD”. On many occasions, they are the same, but for the odd command, I use another method. If you see the label “(Do not run)” use “MY METHOD” instead of “BIGCOMMERCE INSTRUCTION”.

A. # Install Node Version Manager (nvm)

BIGCOMMERCE INSTRUCTION: (Do not run)

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash

MY METHOD: Different / Ran this instead

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.36.0/install.sh | bash

Note that NVM is being installed from this NVM Github page and they have a new version (0.36.0 vs. 0.31.0), so I run the new version.

I then run this command to verify installation:

command -v nvm
returns: nvm 
# nvm is the correct ouput

B. # Install Stencil CLI supported version of Node.js

BIGCOMMERCE INSTRUCTION: (Do not run)

nvm install 10.16

MY METHOD: Different / Ran this instead

nvm install 10.17.0
---------------------------------------------------
Note: in some cases, this error message may occur:
nvm is not compatible with the npm config "prefix" option: currently set to "/usr/local"
Run `npm config delete prefix` or `nvm use --delete-prefix v10.17.0` to unset it.
Make sure your username (blakecronyn) matches the one in your $HOME path.
See the "macOS Troubleshooting" section in the docs for more information.
Consequently, run this command:
nvm use --delete-prefix v10.17.0
return: Now using node v10.17.0 (npm v6.11.3)

Note that the above BC command is telling me to install a specific version of NVM. However, I want to check the Stencil CLI Github page to see if other/newer versions are supported. It states:

Stencil requires the Node.js runtime environment, version 10.x and 12.x (Recommended) are supported. We do not yet have support for versions greater than Node 12.

So, it looks like anything between 10 & 12 is good, so we could use 10.16.

However, when I download Cornerstone or Hero themes and run “npm version” it returns: “ node: ‘10.17.0’ ”. So I think I’m going to use 10.17.0 (see next step).

C. # Switch to Stencil CLI supported version of Node.js:

BIGCOMMERCE INSTRUCTION: (Do not run)

nvm use 10.16

MY METHOD: Different / Ran this instead

nvm use 10.17.0

Note that I use version 10.17.0 instead.

D. # Install Stencil CLI

BIGCOMMERCE INSTRUCTION:

npm install -g @bigcommerce/stencil-cli

MY METHOD: The Same

Note that this installs Stencil CLI version 2.1.1. Everything seems to be working up until this point, although there were a lot of deprecation/warning messages when installing stencil CLI.

3. I then start the second part of the installation process found on BigCommerce’s Dev Center for Stencil CLI.

A. # move into theme dir

BIGCOMMERCE INSTRUCTION:

cd ~/path/to/theme/dir

MY METHOD: (Personalized to the user)

cd /Users/xxxxxx/Desktop/bigcommerce/Cornerstone-4.10.0

Note that this path varies according to each user’s folder path.

B. # initialize a new .stencil config for the theme

BIGCOMMERCE INSTRUCTION:

stencil init
What is the URL of your store's home page? [https://xxxxxxxxxxx.mybigcommerce.com]
What is your Stencil OAuth Access Token?
[ACCESS TOKEN]
What port would you like to run the server on?
3000

MY METHOD: The Same

Note that the return value stencil init does say: “You are now ready to go! To start developing, run $ stencil start”. But we can’t run stencil start until npm install has been run.

C. # install theme modules

BIGCOMMERCE INSTRUCTION:

npm install

MY METHOD: The Same

Note that it seemed to work although there were deprecation/warning messages. As well as a message that indicates “found 269 vulnerabilities (40 low, 167 moderate, 60 high, 2 critical)”. However, from previous experience, I can still access the theme without errors without addressing these vulnerabilities.

D. # serve a live, Browsersync enabled preview of the theme

BIGCOMMERCE INSTRUCTION:

stencil start

MY METHOD: The Same

Conclusion:

While this process is fairly simple, I have run into many issues due to (a) Node version, (b) stencil version, (c) Xcode version with the error message “No Xcode or CLT version detected!”, (d) and errors that relate to node_modules such as “Module build failed (from ./node_modules/babel-loader/lib/index.js)”. There were a couple of helpful commands that I used (referenced above), which allowed me to understand version compatibility and assist with getting Stencil CLI set up, so that I could do what we love: BigCommerce Theme development! If you have any questions, don’t hesitate to reach out at blake@allonecity.com.