Gulp boilerplate

A front-end boilerplate using Gulp as build tool. Based on Yeoman's webapp generator, various other blogs/tutorials and my own experience.

What this boilerplate does for you:

• Live reloading and synchronization with BrowserSync
• Lints and minifies JavaScript.
• Compiles Sass with libSass. Writes sourcemaps in development.
• Autoprefixes, minifies and removes unused CSS.
• Media query optimization: merges matching media queries into one definition.
• Optimizes images - PNG, JPG, GIF and SVG.
• Handles file concatentation with gulp-useref.
• Automatically injects assets from your bower_components to your HTML/SCSS files.

A few basic styles and mixins are included, as well as a JavaScript file with best practices based on a podcast from DevTips. These are completely optional and can be removed or altered according to your liking.

Getting started

1. Installation

• Requirements
• Quick start

2. Project structure
3. Configuration

• Sass
• Modernizr
• Bower components
• Changing the folder structure

4. Dependencies

Installation

Requirements

• Node.js

OS X users can install Node with Homebrew.

$ brew install node

• Gulp

Install Gulp globally on your machine.

$ npm install -g gulp-cli

• Bower

Install bower globally. We use bower to manage our front-end packages (like jQuery, Normalize.css, ...).

$ npm install -g bower

Quick start

1. Get the latest version

Download or clone the latest version of this boilerplate on your local machine by running:

$ git clone https://github.com/ZiggyV/gulp-sass-boilerplate.git MyProject  
$ cd MyProject

2. Install dependencies

Install our project dependencies and developer tools listed in package.json and bower.json by running:

$ npm install  
$ bower install  

// or run them both at the same time:
$ npm install && bower install

3. Start developing

When it's done installing, you can start developing by running:

$ gulp dev

This command will build our project from the source files (src/) into a temporary folder (.tmp/). Also starts a local web server that watches our files for changes.

http://localhost:3000 - BrowserSync server
http://localhost:3001 - BrowserSync control panel

Whenever you modify any of the files in the src/ folder, our project will be recompiled and the browser refreshes automatically. Note that the gulp dev command will not optimize or minifiy any of the compiled output files. This command is for development only.

Don't know how to cancel a command in your terminal? Simply hit CTRL+C

What are these style guidelines?
This is to help me keep consistent throughout my project :). You can easily remove these by deleting styleguide.html and scss/partials/_styleguide.scss in the src/ folder.

4. Build

If your project is ready to go online, create a production-ready build by running:

$ gulp

After running this command, the dist/ folder will contain our production-ready build. You can now copy its contents to your site's /public_html/ via a FTP client like FileZilla.

Project structure

This is how the project structure looks like:

gulp-sass-boilerplate/
│
├── .tmp/                     # Temporary compiled files; used in development only
├── bower_components/         # 3rd party front-end packages
├── dist/                     # Compiled, production-ready output
├── node_modules/             # 3rd party libraries and utilities
├── src/                      # Source code; these are the only files you need to touch 
│   ├── fonts/                # Project fonts; Overpass font is included by default
│   ├── images/               # Images folder; can have subdirectories
│   ├── scripts/              # Scripts folder; can have subdirectories
│   ├── scss/                 # Sass folder; more information below
│   └── index.html            # Homepage of our project; HTML can be in subdirectories of `src/`
├── bower.json                # List of 3rd party front-end packages
├── modernizr-config.json     # List of modernizr feature detects we want
└── package.json              # List of 3rd party libraries and utilities

What about static files?
Static files can be placed in the root of the src folder and they will be copied into the dist folder without changing anything (e.g. favicon.ico, robots.txt, ...).

Note: Make sure you are working in the src/ folder. The gulp and gulp dev commands will delete the dist/ and .tmp/ folder before compiling again, so changes made in these folders will be lost.

Configuration

Sass

This boilerplate uses Sass as its CSS preprocessor. To keep our code clean and DRY (Don't Repeat Yourself), we split our Sass code into multiple files and folders. This boilerplate is based on the Sass Guidelines architecture, but it only uses 4 different folders and 1 main file (main.scss) where we import all of our seperate files.

Our Sass folder structure looks like this:

scss/
│
├── base/
│   ├── _animations.scss      # Animations (keyframes)
│   ├── _base.scsss           # Commonly used standard styles
│   └── _fonts.scss           # Fonts
├── pages/
│   ├── _index.scss           # Homepage specific styles
│   └── _styleguide.scss      # Styleguide specific styles
├── partials/   
│   ├── _buttons.scss         # Buttons
│   ├── _footer.scss          # Footer
│   ├── _forms.scss           # Forms
│   ├── _grid.scss            # Grid system
│   └── _navbar.scss          # Navigation bar
├── utils/                   
│   ├── _functions.scss       # Sass funtions
│   ├── _mixins.scss          # Sass mixins
│   ├── _placeholders.scss    # Sass placeholders
│   └── _variables.scss       # Sass variables
└── main.scss                 # Main Sass file

Note: You can modify this structure to your liking or your project needs. I highly suggest reading the Sass Guidelines 7-1 pattern if you want a more in-depth explanation.

Modernizr

Modernizr is a JavaScript library to detect what HTML, CSS and JS features are supported by your visitor's browser. As you may have noticed, there is a modernizr-config.json included in the root of our project. In this file we specify which feature detections we need for our project.

Basically it adds several classes to the <html> tag. If a feature isn't supported by the current browser these classes will be prefixed by no-.

For example: We have a CSS animation and we want to detect if the user's browser supports this feature. When Modernizr runs in a browser that does support this feature, the <html> element will look like this:

<html class="js cssanimations>"

If the user's browser doesn't support it:

<html class="js no-cssanimations>"

so now we can write custom css for browsers that don't support animations:

.no-cssanimations .myElement {
  /* write our fallback CSS */
}

Note: Which feature detections you need are different for every project. You can generate your own Modernirz config file or change the one included in this boilerplate.

Generate the modernizr.js file
Now that our config file is in order, we still need to generate the actual JS file.

• Install the Modernizr command line tool

$ npm install -g modernizr

• Generate our modernizr.js file to the desired folder

$ modernizr -c modernizr-config.json -d src/scripts 

-c stands for config, while -d stands for the destination folder

• Include the generated file in our HTML

<!-- build:js js/main.js -->
<script src="scripts/modernizr.js"></script>
<script src="scripts/main.js"></script>
<!-- endbuild -->

Read this comment by Paul Irish whether or not you should include the modernizr.js file in the <head> or at the bottom of your HTML.

Bower components

Bower is used to include 3rd party front-end packages in our project. This boilerplate includes jQuery, Normalize.css and Font Awesome out-of-the-box. But how can you add other packages? Well it's fairly simple:

While gulp dev is running, you can install Bower packages like you normally would:

$ bower install --save <package>

Because gulp dev is running, it watches the bower.json file and runs the wiredep task on change. This task will automatically inject assets from bower_components into our HTML/SCSS files (between the bower:{css,scss,js} blocks).

Note: If you don't use the --save flag, our bower.json file won't be updated. The same goes for installing a package with the --save-dev flag. So make sure to use the --save flag when installing a Bower package.

For example: We want to install the animate.css package with Bower:

• Install the package while gulp dev is running

$ bower install --save animate.css

now our HTML files will look like this:

<!-- bower:css -->
<link rel="stylesheet" href="/bower_components/animate.css/animate.css" />
<!-- endbower -->

Notice how the asset gets injected automatically? Pretty neat, right? This just proves how powerful this feature is! You can install and use Bower packages with just one command without the need of updating your files manually.

HTML/SCSS files not updating automatically?
If there are any problems, it's probally due to an incorrect main field in the package's bower.json file. This field value determines which asset the wiredep task is going to inject in our HTML/SCSS. Luckily for us we can override this value in our own bower.json.

You installed a package while gulp dev wasn't running?
No problem! Simply run the gulp wirdep task manually and you are good to go :).

Changing the folder structure

The current structure is just a representation of what I like to use. Ofcourse you can change the project structure or rename folders to your liking, but you will need to adjust a few things in the gulpfile.js, namely the config object.

So if you rename a folder, don't forget to change the corresponding key in the object!

Dependencies

A list of all the dependencies used in this project and a brief explanation for what it is used.

NPM

• autoprefixer: Automatically adds vendor prefixes to CSS rules.
• browser-sync: Creates a small server. Used in this project for live reloading and synchronization between browsers.
• del: Deletes files and folders. In this case the dist/ and .tmp/ folder whenever you run the gulp or gulp dev command.
• gulp: Build system that automates common tasks during development.
• gulp-cache: Caches result of a task.
• gulp-concat: Concatenates multiple files into one.
• gulp-cssnano: Minifies and optimizes CSS.
• gulp-htmlmin: Minifies HTML.
• gulp-if: Conditionally run tasks.
• gulp-imagemin: Optimizes images - PNG, JPG, GIF and SVG.
• gulp-jshint: Gulp plugin for JSHint. Lints JavaScript errors.
• gulp-merge-media-queries: Merges matching media queries into one definition. Very useful since I use a breakpoint mixin which outputs to multiple @media rules when compiled. Mmq will merge matching media queries into one rule.
• gulp-plumber: Prevents pipe breaking caused by errors from gulp plugins.
• gulp-postcss: Pipe CSS through several preprocessors (autoprefixer, cssnano), but only parse it once.
• gulp-purgecss: Removes unused CSS. Great for cleaning up external resources (e.g. Bootstrap, Font Awesome).
• gulp-sass: Compiles Sass to CSS with libSass.
• gulp-sequence: Perform gulp tasks in a specific sequence. Used in this project to clean our .tmp/ and dist/ folders before other tasks run.
• gulp-size: Display the size of the compiled output in your command line/terminal.
• gulp-sourcemaps: Adds inline or external source maps. Useful when debugging compressed code.
• gulp-uglify: Minifies JavaScript.
• gulp-useref: Concatenates files between build blocks in your HTML.
• jshint: Detects errors in your JavaScript code.
• lazypipe: Allows you to create a lazily-initialized pipeline.
• main-bower-files: Returns all main bower files specified in bower.json. This can be overwritten in our own bower.json and you can also filter on a certain file type.
• wiredep: Automatically includes your Bower components between the bower blocks in your HTML/SCSS. Based on your dependencies in the bower.json file. devDependencies will not be injected automatically.

Bower

• jquery: JavaScript library.
• normalize-css: Preserves useful default, unlike most CSS resets.
• font-awesome: Icon font.

License

The MIT License (MIT)