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.