Customization

The best way to turn Snipcart into the fully custom shopping cart we promised you is to use our snipcart-theme project on GitHub.

We suggest you fork the repository and start working from it. You can read about how to fork an existing repository on Github.

The project consists of several scss files. We used the BEM methodology and really decided to go ahead with a component-based files organization.

Files organization

After cloning the repository, you'll have the following files tree:

│   .editorconfig
│   .gitignore
│   appveyor.yml
│   Gulpfile.coffee
│   package.json
│   README.md
├───themes                  
│   └───base                           
│       ├───fonts                      
│       │   └───snipcart               
│       ├───img                        
│       └───sass                       
│           ├───Components             
│           ├───Settings               
│           └───Tools                  
└───tools                              
    └───AzureStorageContentTypeUpdater

The Components folder contains styles for each cart parts. You can change things in them if you want to do an advanced customization.

The Settings folder is where we set up each variable & each color used in the components. You can actually achieve a lot of customization just by changing some variables in these files.

The _colors.scss file contains the color palettes for every component. We suggest you take a look at it directly on GitHub, but here's what it looks like:

$palettes: (
    action: (
        link: #999
    ),
    button: (
        background: #555,
        background--highlight: #efe778,
        background--hover: darken(#555, 10%),
        background--highlight-hover: darken(#efe778, 10%),
        color: #fff,
        color--highlight: #222
    ),
    ...

We decoupled everything to make it easy to change different component colors.

The _font.scss file is used to manage the font sizes everywhere in the cart. We are using a similar function as the one used in _colors.scss to keep things clear.

We then have the _icons.scss file that contains every icon used in the cart. You can easily swap the little truck icon, for instance, to any other you'd like just by changing the variable in this file.

The _mediaQueries.scss file is used to define breakpoints for responsive layouts. You may need to change them depending on the level of customization you do, but if you only change some colors, we suggest you keep them as they are.

The last one, the _reset.scss is used to make sure Snipcart does not get altered by your own site. We reset a lot of things to control how Snipcart will be displayed. We highly suggest you don't make changes to it, but again, if you work on an advanced customization it might be necessary.

The Tools folder contains some mixins and functions to make your life easier. Thanks to Sass for providing this. The best way to understand it is to look at the code directly on GitHub.

Using Gulp

We wrote a Gulpfile that will help you get started. It contains every task you will need to build your own version of snipcart.css.

We suggest you read this post to understand why we chose Gulp in the first place.

We'll describe below the different Gulp tasks we expose.

sass

Usage: gulp sass

This task will compile the sass files and bundle everything in a single css file named snipcart.css. This file will be created in themes/base folder. The file generated won't be minified, so we suggest you don't use it in production.

min

Usage: gulp min

This task will first call the sass one. It will then minify the file and generate a snipcart.min.css file in the themes/base folder as well. We suggest you use this file in production. You should always serve minified assets to increase performance.

watch

Usage: gulp watch

This task is useful when developing your integration. It will watch your file system and, as soon as you change any scss file, it will recompile the snipcart.css file. You will then just have to refresh your browser.

sync

Usage: gulp sync --proxy http://dev.local

This task will start a browsersync server. You can specify the URL you want to create a proxy over. We suggest you create a proxy over your development URL and access your website via http://localhost:3005. You will need to include our file like this:

<link href="http://localhost:3005/themes/base/snipcart.css" rel="stylesheet" />

Then you can access your website directly on http://localhost:3005 and your browser will be refreshed whenever you make a change to any scss file. This is our suggested way to proceed when developing a theme; it will increase your performance!

Deploying

Once your theme is completed, you can run the gulp min task and host the generated snipcart.min.css file directly on your server. Use this file instead of the one we provide on our CDN.

Updates

Snipcart will continue to evolve, but every release that will impact the cart markup will be done by incrementing our minor version number. So it won't break your custom theme. If you want to stay up to date with our latest versions, we suggest pulling changes from our base repository and making the changes needed.