Setting up your BigCommerce theme for development

If you have development experience, BigCommerce provides the ability to download themes and alter the JavaScript, CSS and Handlebars templates.

This document is intended as a quick-start guide for developers wanting to set up one of Pixel Union's BigCommerce themes for local development. For detailed documentation about the Stencil framework itself, please refer to BigCommerce's own documentation.

Pixel Union cannot provide support for themes that have been downloaded and customized. We cannot be held liable for any defects or bugs that arise due to customization by a third party. Please make alterations at your own risk.

Also, please note that while we make a theme's source code available to those who have purchased it, we retain the rights to all theme designs. You are not permitted to upload a derived theme to any theme marketplace (whether BigCommerce's or third-party), nor sell it in any form whatsoever. By downloading and/or altering a Pixel Union theme, you continue to be bound to our Terms & Conditions.

Prerequisites

Before attempting to make any changes to your BigCommerce theme, we recommend familiarity with the following:

• The command-line interface and basic shell commands
• node.js and npm (installation of a node version management system such as nvm is recommended
• the Sass CSS preprocessor
• JavaScript, jQuery and the ES2015 syntax
• The Handlebars.js templating language

More documentation about Stencil theme prerequisites can be found here.

Download the theme

In order to make alterations to a theme, you must have purchased it first.

First, ensure that your theme is fully up to date with the latest version available. Download the theme bundle from your BigCommerce Control Panel. You can find this by navigating to Storefront Design and clicking the theme you would like to download. At the top right under Theme Options you'll have the option to Download Theme. Download the theme and unzip it.

Install the Stencil CLI tools

$ npm install -g @bigcommerce/stencil-cli

More information on installing and troubleshooting stencil-cli can be found here.

Install theme dependencies

After ensuring that you have a working SSH connection to GitHub and BitBucket, run the following command:

$ npm install

Generate an API key for your store

The Stencil framework operates by pulling live data from a BigCommerce shop into your local theme. To enable this, you must create an API key for your store.

From your BigCommerce Control Panel, navigate to Advanced Settings and then Legacy API Settings. Click on Create a Legacy API Account. Enter a username for your account, and save a reference to both the username and generated API key. Hit Save.

Initialize the theme locally

Using the command line, from your theme's directory, run the following command:

$ stencil init

You will be prompted to enter your API account username, token, and store URL. You may also choose which port you'd like the theme to run.

Launch the theme locally

Once you have initialized Stencil, run the following command:

$ stencil start

This will launch a local instance of your theme. You can find more documentation about stencil options here.

Re-uploading an altered theme

Once you have made changes to your theme, re-bundle it with the following command:

$ stencil bundle

This will generate an updated .zip file which you can upload to your BigCommerce Control Panel. You can find troubleshooting tips on bundling and uploading theme zips here.

Troubleshooting

For tips on how to resolve common issues, please refer to BigCommerce's Troubleshooting notes.

Happy developing!