About Bundling and Uploading a Theme
Confirm Dependencies
Before you package your theme, make sure your theme directory includes all the dependencies that BigCommerce requires for submission.
No Automatic Check for Dependencies
The stencil bundle and stencil push commands do not check for the dependencies that these build systems install. So if those dependencies are missing, these commands will not immediately report errors. However, your resulting .zip file will not properly upload to BigCommerce, and will not run properly on a storefront.
Bundling Your Theme
Once you have verified the requirements above, you are ready to process and package your theme for upload to BigCommerce. Stencil CLI provides two options for creating a .zip file that contains all of your theme’s essentials while excluding redundant components. The options are either only bundling your theme or bundling and pushing your theme. These options are available depending on how you’ve authorized your theme:
Bundle Only
The stencil bundle command is available for all themes, whether they were initialized using OAuth or Basic-Auth tokens.
Enter the following on your command line:
The bundle command will notify you of its progress and completion. The resulting .zip file will be located in the theme directory.
”stencil bundle” command
What Happens when the “stencil bundle” command is run?
It takes the HTML templates, SCSS stylesheets and JS scripts source files, and transforms them into a ZIP file, containing the theme files in the format expected by BigCommerce to be applied in a store and work. This transformation from the original source files into another set of files is what we call the build process.
The zipped bundle is required to be less than 50MB. It should only be a few megabytes, but any zipfile approaching 50MB is problematic. If your zip file fits comfortably within the size limit, jump directly to Pushing Your Theme. However, if your zip file approaches or exceeds 50 MB, you must first use one of these procedures to restructure your theme to a manageable size for upload to BigCommerce:
Uploading Your Theme
BigCommerce provides two alternatives for uploading a theme to its associated BigCommerce store. You can perform either a Control Panel Upload or a Command Line Upload. In this course, we will upload using the Command Line Upload.
Command Line Upload (OAuth Required)
The “stencil push” command allows you to both bundle your theme and upload it to the store, with a single terminal command. To run stencil push, you must first:
- Successfully initialize your theme using an OAuth token that was created with the Themes:modify scope. Install the latest Stencil CLI version.
- To check your current Stencil CLI version, enter
stencil --versionorstencil -Von the command line. If you need to update an earlier version, reinstall Stencil CLI.
If your store utilizes BigCommerce’s Stencil CLI for storefront management, we strongly advise promptly upgrading to the most recent Stencil version. This will provide your team with access to the latest advancements and capabilities.
Pushing a Theme Upload
To initiate bundling and upload, enter the following on the command line:
Stencil CLI is designed to display the same notifications, prompts and selection options that you would receive when using the control panel’s GUI.
To push a theme and activate a particular variation without being prompted, use stencil push -a VARIATION_NAME with the name of the variation. For example, stencil push -a Light will activate the “Light” variation. If you simply use stencil push -a without a variation name, the first variation will be applied.
To push a theme and apply it to selected channels, use stencil push -a -c 123 456. To apply a theme to all available channels, use stencil push -a -allc.
If you are already at your theme limit, you can automatically delete the oldest theme on your store using stencil push -d. You can use the combination, stencil push -a -d, to give the best chance of the upload working without any interaction, which is desirable for automated deployments of Stencil CLI.
Successful Bundling
Stencil CLI will display “ok” confirmations, “not okay” errors or warnings for individual substeps in bundling and uploading your theme. If bundling is successful, you will next see a “Processing” progress bar to track the upload.
Successful Upload
Upon successful upload, you will receive the prompt, “Would you like to apply your theme to your store at <storehash>? (y/N).” Any response except “y” or “Y” processes as “No.” You can always apply the theme later through the control panel.
Resources
Bundling and Pushing a Theme
