gulp-boilerplate
A gulp ITCSS Sass based boilerplate for individuals and teams.
Lints and concatenates JS files. Compiles Sass files and automatically adds vendor prefixes. Exports both minified JS and CSS files with header info. Generates SVG sprites.
Contents
Getting Started
Dependencies
Make sure these are installed first.
Quick Start
- In bash/terminal/command line,
cd
into your project directory. - Run
npm install
to install required files. - When it's done installing, run one of the task runners to get going:
npm start
automatically watch for changes and compile files, lints JavaScript and server and synchronise changes to the browser via Browsersync accordingly;npm run lint:sass
lints your sass using stylelint. Rules can be found in the.stylelint
config file.npm run lint:js
lints your JavaScript using eslint. Rules can be found in the.eslintrc
config file.npm run build
manually compile files and lint JavaScript without serving the files to the browser.npm run build:sass
manually compiles just your sass.npm run build:js
manually compiles just your JavaScript.npm run build:images
manually optimizes just your images.npm run build:svg-sprite
manually compiles all your SVG's in a SVG sprite.
File Structure
Add your files to the appropriate src
subdirectories. Gulp will process and and compile them into dist
.
- Content in subdirectories under the
js
directory will be concatenated; - Image files (including svg files) placed in the
img
directory will be optimised and copied into thedist/assets/img
directory; - SVG files placed in the
src/sprite
directory will be optimized and compiled into thedist/assets/img
directory as asprite.svg
file.
gulp-boilerplate/
โโโ dist/
โ โโโ assets/
โ โ โโโ css/
โ โ โ โโโ critical.min.css
โ โ โ โโโ main.min.css
โ โ โโโ fonts/
โ โ โ โโโ # font files
โ โ โโโ img/
โ โ โ โโโ # image files
โ โ โโโ js/
โ โ โโโ scripts.min.js
โ โโโ .htaccess
โ โโโ favicon.icon
โ โโโ humans.txt
โ โโโ index.html
โ โโโ manifest.json
โ โโโ robots.txt
โ โโโ service-worker.js
โ โโโ # static assets
โโโ src/
โ โโโ img/
โ โ โโโ # image files
โ โ โโโ touch/
โ โ โ โโโ apple-touch-icon.png
โ โ โ โโโ chrome-touch-icon-192x192.png
โ โ โ โโโ icon.png
โ โ โ โโโ ms-touch-icon-144x144-precomposed.png
โ โโโ js/
โ โ โโโ # script files
โ โโโ scss/
โ โโโ sprite/
โโโ .babelrc
โโโ .editorconfig
โโโ .eslintrc
โโโ .gitignore
โโโ .stylelintrc
โโโ gulp-options.json
โโโ gulpfile.babel.js
โโโ LICENSE
โโโ package.json
โโโ readme.md
Working with the Source Files
Sass
This project uses the ITCSS structure and makes use of imports to allow for a critical stylesheet to be generated alongside you main stylesheet.
Sass files are located in src
> sass
. Gulp generates minified and unminified CSS files. It also includes autoprefixer, which adds vendor prefixes for you if required by the last two versions of a browser.
JavaScript
JavaScript files are located in the src/js
directory.
All script files placed in this directory will be concatinated and minified into a single scripts.min.js
file compiled directly into the dist/assets/js
directory.
Images
Image files placed in the src/img
directory will be optimised and copied into the dist/assets/img
directory. The src/touch
directory contains some placeholder images various touch devices. These are compiled into the subdirectory dist/assets/img/touch
and referenced, if required, in the head of dist/index.html
.
Note: Although the images
task has image optimisation enable through the imagemin plugin images can sometimes be further optimise with ImageOptim and b64.io.
SVG sprite
SVG files placed in the src/svg
directory will be compiled into a single SVG sprite named sprite.svg
and compiled to the dist/assets/img
directory. This can then be loaded into the page with ajax via a snippet which resides in the <head>
of dist/index.html
.
Options and Settings
Updating Project Details
Open up package.json
to change the name, version, URL and other data about the project. The following values are used in the banner which is inserted in the top of the compiled files.
- Name;
- Title;
- URL;
- Author;
- Version;
- License.
Changing the Directory Structure
Inside gulp-options.json
you'll find a json object of directory paths. Adjust the paths to suit your workflow.
{
"src": {
"src": "src",
"scss": "src/scss/**/*.scss",
"img": "src/img/{,*/}*.{jpg,jpeg,png,gif,svg}",
"sprite": "src/sprite/{,*/}*.svg",
"js": "src/js/**/*.js",
"vendor": "src/js/vendor/**/*.js"
},
"dest" : {
"dist": "dist",
"css": "dist/assets/css",
"img": "dist/assets/img",
"js": "dist/assets/js"
}
}
Thanks
- gpmd - For their ITCSS boilerplate.
- Chris Ferdinandi - For his Gulp Boilerplate which parts of this were inspired by.
License
The code is available under the MIT License.