Common Stencil CLI Pitfalls and How to Avoid Them

The Stencil Command Line Interface is a powerful tool that lets you preview BigCommerce theme changes in real time and bundle your files into a zipped theme you can upload to your store. It can seem a bit daunting to dive into this type of development if you’re new to Stencil.

As a moderator in our Developer Community, I’ve noticed that users can get hung up on common errors during the install process. Integrating Stencil development with your local set up and processes will be easy once we go over a few common pitfalls. This post will guide you through jumping into developing on Stencil, and hopefully help reduce the friction you might experience during some of the tricky parts.

Do I need the Stencil CLI?

First and perhaps most importantly, you should determine whether or not you actually need to install the Stencil CLI to make the design changes you want on your store. Work smart, not hard!

Here are a few scenarios to help guide you in making that determination.

Q: I’d like to show customers a few more product details on my product pages — like the warranty information — and my current theme doesn’t display this natively. Do I need to install the Stencil CLI?

A: Nope! You can add references to additional Stencil object properties like {{product.warranty}} in a template file without using the CLI. BigCommerce has a built-in theme file editor that you can use to make the changes you need. Check out our guide for accessing your theme files and making changes directly in your Dashboard here.

See our documentation for a list of objects available and the partials where they can be referenced. (Don’t forget to declare new objects in a template with front matter.)

Q: Do I need to install the Stencil CLI to translate my store to additional languages?

A: Yes, this is a situation in which you will need to install the CLI, because you will be adding a new json translation file, and those must be bundled into the theme.

Q: I’d like to create a custom page layout for certain products. Do I need the CLI to do this?

A: Yes, creating a custom template file requires installing Stencil CLI. You’ll need the CLI to preview the custom template with your product page as you work, and to bundle the new file with your theme.

Installing the CLI

We have a straightforward guide for installing the CLI here in the BigCommerce Dev Center, but I want to address a few points during the install process where folks tend to get stuck.

Installing dependencies using Git and npm

I’ve noticed that Windows users will sometimes reach an impasse when it comes time to pulling down Stencil and its dependencies from npm. To do this, you’ll need a shell command-line tool that can run Unix commands. In our documentation, we recommend Git Bash but you can use Powershell or other software.

Once you install Node with the dependencies required to run Stencil, you’ll be able to use the npm command.

Customizing an Existing Theme

In our documentation we recommend you pull down the latest version of Cornerstone from GitHub, but that isn’t necessary if you already have a theme that you want to make changes to.

In this scenario, all you have to do is download your theme from the BigCommerce dashboard. Under Storefront > My Themes click Download Current Theme to download a zip file of your theme.

(Note: For Pixel Union themes, you will need to set up BitBucket SSH keys before this step.)

Next, unzip it and in your shell navigate to the theme directory

cd /files/my_theme

Then run

npm install

Be aware of dependency versions

The number one issue I have observed users run into when installing the Stencil CLI is they’re not using the recommended version of Node or Python, or aren’t using the most recent version of the CLI itself.

If you downloaded the CLI a while ago, now would be a good time to install the latest version. To make sure this goes smoothly, run

npm uninstall -g @bigcommerce/stencil-cli

then

npm install -g @bigcommerce/stencil-cli

This uninstalls and reinstalls the CLI globally.

With Node, we’ve tested versions 6.10.3 to 8.12.0. If you’re using an earlier or later version, you may see an error like this when you run stencil init — in addition to a boatload of fun warnings.

fatal error: ‘sass/context.h’ file not found

Okay, what now? First, nuke your Node modules folder.

rm -rf node_modules

Now run nvm install 7.6.0

Once the supported version is successfully installed, run nvm use 7.60and double check you’re using it by running node -v. You should now see that you’re using the supported version

Now using node v7.6.0 (npm v6.8.0)

Finally, run npm installin your theme directory and you should be able to successfully install all Node modules, and when you run stencil init, you shouldn’t see any errors. When you’re ready to start developing, run stencil start!

Frequently Asked Questions

Q: I am seeing an error when running npm install :npm ERR! Please try running this command again as root/Administrator.

A: You’ll want to try forcing an npm cache clean as the administrator:

sudo cache clean -f

Then run npm installagain.

Q: I am seeing a 500 error when running stencil init. Is this due to an error on BigCommerce’s end?

A: There are a few things to check when this happens:

• Make sure you are using a recommended version of Node
• You will see this error if you do not have a Stencil theme applied on your BigCommerce Store.
• This could be a side effect of making a request to a store using a proxy-based domain service like Cloudflare or Amazon Cloudfront. If you suspect this is the culprit, modify the hosts file on your machine to map your localhost to the BigCommerce IP of your store.

Q: I was able to install and set up Stencil, but I’m seeing a 404 error when trying to preview a custom template file!

A: The reason you’re getting this error is because you need to first create a corresponding page in your live store with the same URL that you mapped the custom template to in your .stencil file. For example, let’s say you’ve already edited the .stencil file to include a key for a custom product template:

“product”: {
“alternate-product.html”:”/test-url/”
}

You must log in to the control panel of your BigCommerce store and create a product with the URL /test-url/ .

Final Thoughts

Once you break down the install process, it becomes much easier to troubleshoot each step. If you’re still lost, have a specific setup, or just want to chat with other developers about advanced Stencil development, head over to the Developer Community. Have an interesting Stencil project you’re working on? Tweet @BigcommerceDevs — we want to hear about it!