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.


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.

  1. 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

    All current releases of our themes use  npm and webpack to manage and bundle JavaScript dependencies. Any version before v1.10.0 used JSPM and SystemJS.

    1. Setup for npm themes:

      For npm/webpack themes, simply navigate to the theme directory and run npm install. This should install all theme dependencies.

    2. Setup for jspm themes:

      1. Install jspm
        $ npm install -g jspm<br>
      2. Install and configure jspm-git Pixel Union hosts JavaScript dependency modules on BitBucket, and jspm does not recognize BitBucket as a valid registry by default. Run the following commands:
        $ npm install -g jspm-git
        $ jspm registry create bitbucket jspm-git<br>

        Enter ssh:// as the base URL when configuring.

      3. Install theme dependencies Navigate to the theme directory, and run the following commands:
        $ npm install
        $ jspm install<br>
  2. 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.

  3. Initialize the theme locally

    Using the command line, from your theme's directory, run the following command:
    $ stencil init<br>

    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.

  4. Launch the theme locally

    Once you have initialized Stencil, run the following command:
    $ stencil start<br>

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

  5. Re-uploading an altered theme

    Once you have made changes to your theme, re-bundle it with the following command:
    $ stencil bundle<br>

    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.

Happy developing!