Setting up your BigCommerce theme for development
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.
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
- 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.
Determine which package manager the theme uses
Setup for npm themes:
For npm/webpack themes, simply navigate to the theme directory and run npm install. This should install all theme dependencies.
Setup for jspm themes:
- Install jspm
$ npm install -g jspm
$ npm install -g jspm-git $ jspm registry create bitbucket jspm-git
ssh://firstname.lastname@example.org the base URL when configuring.
- Install theme dependencies Navigate to the theme directory, and run the following commands:
$ npm install $ jspm install
- Install jspm
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 locallyUsing 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 locallyOnce 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
Re-uploading an altered themeOnce 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.
For tips on how to resolve common issues, please refer to BigCommerce's Troubleshooting notes.