After building and supporting BigCommerce stores for over a decade, we’ve learned how to develop stores while keeping them as efficient as possible. This includes building in a way that will let store owners be reasonably able to update and maintain their stores going forward.
Here are our recommendations for best practices for BigCommerce development:
Edit as FEW files as possible
This is really important. Develop for updating.
At some point you or your client will want to install updates on their theme, to keep up with new features as they come out. For this reason, its important to understand the updating process.
When BigCommerce theme updates come out, they can be applied to the original theme, but do not apply to your forked theme. This is deliberate, so that updates don’t potentially break anything in your store due to conflicts with the customizations you make.
So if you’re on version 4.5 and 5.1 is out, the way to upgrade your theme is to compare the files between the two themes. We recommend using a difference checker like KDIFF to do this. Wherever there are differences, those are either customizations, which need to be brought forward, or they’re theme updates that also need to be brought forward.
Long story short… the more files have been customized, the more files you’ll need to manually go through and decide to bring forward code.
Keep your customizations in fewer areas and it will be a much easier time. For example maybe hide something with css instead of deleting it out.
Consolidate all CSS changes to 1 custom css file
There are loads of css files built into BigCommerce.
Don’t customize those.
Instead, create a new css file, and reference it last in your theme.scss file.
We recommend calling the file custom.scss, and putting it in your ASSETS>SCSS folder, then adding the following line at the bottom of theme.scss:
@import “custom”;
Of course you can only do this using stencil local environment.
Where to Add Javascript
Be very wary of editing existing javascripts.
If you REALLY have to edit the way an existing javascript works, then you may have to, and just deal with the complexity created in updates in the future. Leave very obvious comments if you have to do this.
Most of the time though, you don’t have to.
If its a store script, not really having anything to do with the actual theme… like a script that installs an obsure app… then you’re probably best off to install it in the data solutions panel in the backend. Preferrably in the visual website optimizer tab.
If its a script that needs installed in different places in the theme, like a piece on the category page and another piece on the product page… then you pretty much need to get into the theme to do it.
If its a custom script, then we recommend to put it into the file it will interact with, like into product.php if it will interact with that. If it’s a site-wide script, then base.html is your outtermost wrapper and the best place to put it.
No matter where you put it though… leave comments, preferrably before and after, to make it more obvious for when you’re updating later.
Surround Custom Code With Comments
Again this is all about laying down a good foundation for updating the theme later.
Alter as few files as possible, but try to make the edits loud with comments as much as you can.
When you use the difference checker later to make updates, you’ll appreciate this and it will make updates way less problematic.
Use SASS Variables For Colors
BigCommerce uses SCSS / SASS on purpose.
This makes it really efficient to do things like declare a color variable, and reference the variable later in the scss.
Example:
$black: #292929;
h2 { color: $black;}
You can use variables for plenty other things like fonts too…
Don’t Apply Styling With Javascript
Styling you apply with javascript is hard to update down the road.
Instead, apply a class with javascript if you need it to power a change… and apply styling to the class in scss. Then its easy to change styling later.
Comment Out Code You Don’t Need
Please. Stop. Deleting stuff.
There are two reasons for this.
1> The business owner will have a hard time figuring out how to get that code back later if they decide they wanted that functionality after all. Or even figuring out why it is gone in the first place.
2> When you go to update the theme, the code you deleted will show up again and be brought forward, which will probably cause some problems. If you just comment it out today, it will be obvious that it was taken out deliberately later.
So just stop deleting please.
Build on the Cornerstone Theme
All the most experienced BigCommerce developers build on BigCommerce’s flagship theme… Cornerstone. Here is why:
1> It’s free. This is the weakest reason, but its still kinda nice.
2> It’s got all the latest features in it. BigCommerce puts this out as an example of how to best implement available features. It’s up to other theme manufacturers if they want to update and include new features. Some of them do. Some of theme don’t. You want to start with all of theme, so start with Cornerstone
3> It’s the easiest to update. Even though you’re forking off the main theme, when an update comes out, its really nice to be able to compare your forked theme to the new updated theme. This effectively gives you a map to update your fork (using KDIFF)
4> It’s lean and mean. BECAUSE it doesn’t have all that flashy stuff you saw in that theme forest theme… it also doesn’t have extraneous junk slowing it down. For goodness sake… speedtest the Cornerstone demo site against the demo site of whatever theme you were THINKING about using. Cornerstone will be faster because its purposefully minimal. If you want your site to end up fast, you gotta start fast to get there…
Apply Styling With Classes When Possible
It’s not only a bad habit to style everything separately in css… it’s also a great way to build inconsistencies.
So instead of styling each title separately, maybe just make a title class and style it site-wide.
We also generally recommend styling your site-wide stuff first, and then overriding it in specific instances like your homepage.
Phew.
I know that’s a lot.
We’ve spent over a decade taking over hodge-podge code and these are some of the best practices we think would help the whole BigCommerce community.
Do you have a pet peave that should be added to our list of best practices? Email us at [email protected] and we’ll consider adding it to the list.
Let’s all challenge each other to improve the code in the BigCommerce ecosphere.
Thanks