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.
OS X users can install Node with Homebrew.
$ brew install node
Install Gulp globally on your machine.
$ npm install -g gulp-cli
Install bower globally. We use bower to manage our front-end packages (like jQuery, Normalize.css, ...).
$ npm install -g bower
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
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
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.
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.
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. Thegulp
andgulp dev
commands will delete thedist/
and.tmp/
folder before compiling again, so changes made in these folders will be lost.
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 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 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, ourbower.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 :).
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!
A list of all the dependencies used in this project and a brief explanation for what it is used.
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 thedist/
and.tmp/
folder whenever you run thegulp
orgulp 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 withlibSass
.gulp-sequence
: Performgulp
tasks in a specific sequence. Used in this project to clean our.tmp/
anddist/
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 betweenbuild
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 inbower.json
. This can be overwritten in our ownbower.json
and you can also filter on a certain file type.wiredep
: Automatically includes your Bower components between thebower
blocks in your HTML/SCSS. Based on your dependencies in thebower.json
file. devDependencies will not be injected automatically.
jquery
: JavaScript library.normalize-css
: Preserves useful default, unlike most CSS resets.font-awesome
: Icon font.