With a standard BigCommerce theme, the BigCommerce Dashboard offers an array of options for controlling the display of your store pages, products and global elements. But if you need more than what comes out of the box, it’s time to develop your own custom theme.
Stencil is the latest theming engine from BigCommerce, and replaces Blueprint. The changes are many, but, as we found, so are the benefits. Stencil is opening up what we think is a whole new world for front-end web development. Sass solutions are notorious for being rigid and difficult to customize. Stencil changes all of that.
A client recently came to us with some unique requirements for their eCommerce site, which was on an existing BigCommerce store. They were looking to rebrand their company with a new look and feel, and streamline their site from a WordPress-BigCommerce Frankenstein to an BigCommerce-only eCommerce machine. Many of their products needed to be presented within the context of a lot of supporting content which would guide the user to the right purchase decisions. They also had very specific aesthetic requirements, having hired a professional designer to create beautiful page mockups which looked nothing like any existing templates available in any theme marketplace. This was going to be a truly custom, BigCommerce-powered UX.
The Stencil Framework and Developer Toolkit
An installation of stencil results in a holistic bundle which includes everything to mimic a live site on the BigCommerce platform in a local development environment, with access to the full capabilities and assets to the live store while making no impact on it.
Under the hood, Stencil is a framework that makes use of webpack, so if you already have experience with other webpack-based frameworks, you will have an easier time understanding the stencil development workflow. Webpack provides the scaffolding for Stencil to utilize a development server, js linter, template and scss compilers, browsersync feature and bundler. While some if its loaders and configurations are unique to stencil, understanding webpack will help with debugging issues.*
Before my first project, I was a little intimidated about working in an environment like this. But, getting ramped up only brought happy surprises as I experienced the many benefits of the included tools.
Setting Up Your BigCommerce Test Store
BigCommerce is a hosted solution. If we wanted, we could have built and tested our theme from our local environment using live client store data and store configuration settings. But we wanted to be able to alter configuration settings and product structure safely to test how views would be affected in the new theme. So, we started by setting up an unpublished test store. (Our status as a Certified BigCommerce Elite development partner allowed us to maintain a trial store as a sandbox for development purposes). Here we were able to import products from the client’s live site for testing, and we could preview the new theme with that data.
Setting Up Stencil
The BigCommerce Stencil documentation offers an excellent step-by-step guide for setting up and configuring Stencil. The first time, I was up and running within about an hour (even with a 4.5 GB XCode download for OS X). BigCommerce has some great reference videos, too. Another developer here at HE, Brian Tajer, also had some thoughts and tips on setting up stencil.
Setting Up Git
Since we would potentially have multiple developers working on the project at the same time, we set up a git repository. Out of the box, Stencil does not utilize proper code tracking or version control, so we applied the normal process we use on other platforms in utilizing GIT. By adding git to track code changes, we were able to do code reviews and test pieces of code thoroughly before bundling them up for live deployment.
Command Line Interface
A single line command strikes up all of your services… “stencil start”. Your scss is watched and compiles on save, and browsersync refreshes your browser to reflect your changes as you go. You are provided a local IP to review your site as you work, and you preview using live data and real-time dashboard config settings.
Browsersync Serendipity
This might be my favorite thing about working in Stencil locally. Save a file in your IDE and see your browser refresh each time. Primarily, it allows for preview and testing across multiple devices/viewports.
Collaborative Visibility
Even while development happens locally, Stencil provides a URL so that others on your network can see your work. This is great for us, as our PMs are always anxious to review progress. (Right, John Tucker?).
Yaml
Using YAML templating allowed me to declare the data assets required, and leave out what I didn’t need. It also allowed to override default settings at the template level.
Leaving Lint Alone
By default, Stencil sets the linter to enforce the strictest of rules, which can create a few hurdles if your scripts are not fully compliant with ECMAScript 6 specifications. We choose not to mess with this to curtail any risk of incompatibility with BigCommerce functions.
DOWN TO WORK
If BigCommerce is new to you, it is a good idea of have a solid handle on the BigCommerce dashboard settings and functionality before diving in so you know what your client can and cannot control, and so that many of the functions and objects you see throughout the theme files will make sense. This might seem obvious, but spend a day learning how their product options work, how categories are set up and displayed, and how to configure different product types. It will save you time in the long run.
Start with a Base Theme
If you’re starting from scratch, you need to start with a base Stencil theme. If you’re currently on a Blueprint-based theme, you’ll need to find a new Stencil-ready theme to start from. In order to use Stencil CLI, you must have a Stencil theme. Here’s a list of all the Stencil-ready BigCommerce themes. We started with Cornerstone as the base theme. As with any type of project using a base theme, reviewing available themes prior to the creative design process may save a great deal of time, as there may be something that comes close to what you need and less customization will be required. Using something other than Cornerstone, however, means some unique workflow rules found here.
Initial Customizations
We dove right in to update fields in the config.json file with the name of the theme, colors, default product display options, thumbnail sizes, and even theme variations.
Custom Templates
You can customize per Web Page, Product, Category or Brand. It’s imperative to adhere to the folder structure as required.
Custom Scripts
It may not seem obvious, but third-party or legacy scripts are doable, too. It’s just a matter of putting them into a designated folder named “artifacts”. We set that up, included it in our git repo and we were all set.
Wrapping Up
Bundle and post: Stencil bundle creates a .zip file with the name of your theme as it displays in config.json. It’s a good idea to include the version info there before you bundle (and commit it to git, as well). Then you just upload the zip file to the store through the Dashboard. The theme is unpackaged and processed in the store, and them becomes free to “Apply”. All previous themes remain for re-applying, if desired.
Conclusion
As a front-end developer at Human Element, diving into stencil has been a valuable experience. When I ran into personal roadblocks, I had the advantage of being able to call on one of several geniuses here at Human Element, who had a deeper understanding of the workings on the back-end.
* Special thanks, Nathan Erickson
