#1 Quick Start

Friday, May 11, 2018

In this article we are going to do the basic set up for using SCSS within our project. More specifically we are going to add both Bourbon and Bitters to our project in order to make getting up and running and using SCSS easier and more enjoyable. Both are excellent projects from thoughtbot™.

Christopher R. Jamell

Watch In YouTube

Parts

Part 1: Quick Start

Ruby

The first thing we need to do is install Ruby on our machine if it is not already. If you are working on a machine that is installed with anything other than Windows it is probably already installed. You can check by opening up a console windows and executing the ruby -v command. If Ruby is not installed you can check out the section on their website with installation instructions. Once Ruby is installed we can add the three gems that will be the base of our scss files.

Bourbon

WebUi
- Source
  - sass
    - 0-bourbon
      - bourbon
        
        helpers
        
        _text-inputs-list.scss

The first package that we want to install in our project is Bourbon version 5.0.0. From their documentation:

Bourbon is a library of Sass mixins and functions that are designed to make you a more efficient style sheet author. It is…

Dependency-free: Bourbon is pure Sass.

Human-readable: We aim for clarity over brevity.

Lightweight: Zero output post-install and has no visual opinion.

Before we can install Bourbon in our project we need to install its Ruby gem onto our system. We do that by executing the gem install bourbon command in a console window. Now that it is installed on our system we need to make sure that our console window is pointing at the sass folder and executing the bourbon install command. This will create a folder simply called bourbon inside of our sass folder. Now that it is created I like to rename the folder to 0-bourbon. Within the folder we have just installed there is a file called _text-inputs-list.scss that contains, as it's name implies, a list of all the types of text inputs (a). At first blush this does not seem to be a problem but this list rightfully, if all we are using are standard html elements, assumes that the only elements that would have a type of text would be an input element. Fortunately we are living in the time of web components and I have on occasion myself created a component which which has had an attribute of type text for example. To avoid our components having styles applied to them that we do not want we will modify the list to be (b).

_text-inputs-list.scss (1)

$_text-inputs-list: (
  "[type='color']",
  "[type='date']",
  "[type='datetime']",
  "[type='datetime-local']",
  "[type='email']",
  "[type='month']",
  "[type='number']",
  "[type='password']",
  "[type='search']",
  "[type='tel']",
  "[type='text']",
  "[type='time']",
  "[type='url']",
  "[type='week']",
  ":not([type])",
  "textarea",
);

(a) Original text inputs list created by Bourbon.

_text-inputs-list.scss (2)

$_text-inputs-list: (
  "input[type='color']",
  "input[type='date']",
  "input[type='datetime']",
  "input[type='datetime-local']",
  "input[type='email']",
  "input[type='month']",
  "input[type='number']",
  "input[type='password']",
  "input[type='search']",
  "input[type='tel']",
  "input[type='text']",
  "input[type='time']",
  "input[type='url']",
  "input[type='week']",
  "input:not([type])",
  "textarea",
);

(b) Modified text inputs list so that styles are not automatically applied to custom web components that we create.

At the time of the writing of this article there is a pull request already submitted to handle this problem with an indication the the problem will be resolved in the 5.1 version.

Bitters

WebUi
- Source
  - sass
    - 1-base
      - _base.scss
      - _media-queries.scss

Next up is Bitters version 1.8.0. Again from their documentation:

Bitters helps designers start projects faster by defining a basic set of Sass variables, default element style and project structure. It's been specifically designed for use within web applications. Bitters should live in your project's root Sass directory and we encourage you to modify and extend it to meet your design and brand requirements.

Once again we need to install the gem first, by you quessed it, executing the gem install bitters command. Once that is finished we need to install it in our project by using the bitters install command. Unlike our Bourbon installation that we may reinstall when an update to the gem is made we will not be reinstalling bitters at any point. Due to this fact just like the quote directs us to we are going to modify its contents. The first thing we are going to do is add a file to make adding media queries to our css easier (c). We will be including the contents of our base folder in our main scss file and in order to make sure that we have access to the media queries in that file we are going to modify the _base.scss file to import the media queries (d).

_media-queries.scss (1)

@mixin media-lt($max-width) {
    @media screen and (max-width: $max-width - 1) {
        @content;
    }
}

@mixin media-lt-or-eq($max-width) {
    @media screen and (max-width: $max-width) {
        @content;
    }
}

@mixin media-gt($max-width) {
    @media screen and (min-width: $max-width + 1) {
        @content;
    }
}

@mixin media-gt-or-eq($min-width) {
    @media screen and (min-width: $min-width) {
        @content;
    }
}

@mixin media-between($min-width, $max-width) {
    @media screen and (min-width: $min-width) and (max-width: $max-width) {
        @content;
    }
}

(c) The contents of the media queries file that we added to the Bitters installation to make creating media queries simpler.

_base.scss (1)

...
@import "media-queries";
...

(d) Adding the import to the media queries file so that it is imported when all of the other Bitters files are imported.

Resetting and importing

WebUi
- Source
  - main.site.scss
- index.html

As is mentioned within the Bitters documentation,

Bitters is made to work alongside a CSS reset or style-normalizer; not replace one. We like to use Normalize.

we are going to add a css reset and since we are using their products we are going to go with their recommendation for which one to use and install Normalize. To do that we again return to our console, making sure that we are at the root of our project this time, and execute the npm install --save-dev normalize.css command. Now that all of that is done we can import both our css reset and base installation into a main scss file (e) that we will use to create a main style sheet that can be included in our projects. Not it is time to add a simple html file (f) so that we check to make sure our setup is working correctly.

main.site.scss (1)

@import "../node_modules/normalize.css/normalize.css";
@import "./sass/0-bourbon/_bourbon.scss";
@import "./sass/1-base/_base.scss";

(e) Importing of both our chosen css normalizer as well as the contents of the Bitters installation into our main scss file.

index.html (1)

<!DOCTYPE html>
<html>
<head>
  <title>Sassy Cascading Stylesheets - Quick Start</title>
  <link href="wwwroot/css/main.bundle.css" rel="stylesheet" type="text/css"/>
</head>
<body>
    <label>Test Label</label>
    <input type="text" name="test" value="" />
    <script src="wwwroot/js/main.bundle.js"></script>
</body>
</html>

(f) Simple html test page.

With that done we are now ready to start using SCSS in our projects. If you would like to see how to create a css bundle out of the main.site.scss file you can check out our Webpack quick start. Once we have set up webpack within our project we can execute the npm run build command to generate our bundles. Before we create our bundles if we take a look at the index page we should see that it looks something like (g) and afterwards it should look something like (h). This of course means everything is working and we are ready to move on with our project.

(g) Image showing our simple html test page before creating our css bundle.

(h) Image showing our simple html test page after creating our css bundle.

Exciton Interactive LLC