aaronwaldon/1) readme.md

## 1) readme.md

      
    Raw
  

              1) readme.md
            
          
    How to set up Gulp with a Craft CMS project

I freaking love working with technologies like Gulp, and wanted to share how to get my current Craft front-end workflow set up. With a few tweaks, this can also be used with virtually any other sites (I've used it with Laravel, static sites, ExpressionEngine, etc).
Project Directory Structure


project root/

craft/

templates/

(your craft template files)


public/ (web root)

assets/

styles/
js/
images/


source/

js/

combined/ (these files will be collectively combined and minified and placed in the public/assets/js/ folder as scripts.js and scripts.min.js)
libs/ (useful for things like jquery)
* (various .js files)
plugins/ (useful for things that depend on libs, like plugins)
* (various .js files)
site.js (this is where your hand-coded js will go)
individual/ (these files will be individually minified and combined and placed in the public/assets/js/ folder)

(various .js files)


scss/ (these files will be processed and places in the public/assets/styles folder)

(various .scss files)
styles.scss


gulpfile.js (download and include)
package.json
gulp.png (optional)


Installation

Install Node and Gulp (once per machine)


If Node is not yet installed on the machine, it will need to be installed

Install the node dependencies for the project (once per project, per machine)


If a package.json file already exists with list of all of the dependencies that Gulp will need for the project, then you can simply switch to the project root directory in the site terminal and run the command npm install. This only needs to happen once so that the dependencies can be downloaded for the project.
If a package.json file does not exist, switch to the project root directory for the site in a terminal. For this configuration, you can install gulp and the needed dependencies using the command npm install browser-sync gulp gulp-autoprefixer gulp-concat gulp-cssnano gulp-livereload gulp-newer gulp-notify gulp-plumber gulp-rename gulp-sass gulp-size gulp-sourcemaps gulp-uglify gulp-watch lazypipe node-sass --save-dev. You only need to do this once so that the dependencies can be downloaded for the project.

Add the gulp.js file (once per project)

Copy the gulp.js file (below) to the base of your site. The provided gulp.js file is set up to work with the following project directory structure.

Change 'Your Site Name' to the name of your site.
Change yoursite.dev to the domain name that browserSync will proxy.

Add .gitignore rules (once per project)

If using Git, be sure to add the .gitignore rules to your site's .gitignore file
Run Gulp (every time you want to use it)


To just compile the scripts and SCSS one time, simply run the command gulp.
To watch the templates, .scss, and .js files for changes, and to automatically compile and minify the relevant files, run the command gulp serve-lr. If the livereload browser extensions are installed and enabled, the browser will automatically refresh when any changes are made.
Additionally, you can run the command gulp serve-bs to run browser sync. It will also compile and minify the relevant files and reload the browser. Additionally, it will allow browsers to sync their scrolling and clicks. Also useful for testing the site on local network mobile devices.

Notification image (optional)

Feel free to use an icon for the project notifications. Simply place a png image named gulp.png file in the project root, and the script will use it in the notifications. You can optionally download and include this generic gulp image.

  
## 2) gulpfile.js
// -------------------- Configuration Settings --------------------
var config = {};

//basics
config.siteName = 'Your Site Name';
config.proxyDomain = 'yoursite.dev';

//source directory
config.src = 'source/';

//destinations
config.dest = 'public/assets/';
config.destJS = config.dest + 'js';
config.destCSS = config.dest + 'styles';

//globs
config.globs = {
	scss : config.src + 'scss/**/*.scss',
	js : {
		individual : config.src + 'js/individual/**/*.js',
		combined : [
			config.src + 'js/combined/libs/*.js',
			config.src + 'js/combined/plugins/*.js',
			config.src + 'js/combined/pluginSubs/*.js',
			config.src + 'js/combined/site/*.js',
			config.src + 'js/combined/site.js'
		]
	},
	watched : [
		config.src + 'craft/templates/**/*',
		config.destJS + '/**/*.min.js',
		config.destCSS + '/**/*.min.css'
	]
};

//browser sync
config.browserSync = {
	files: config.globs.watched,
	proxy: config.proxyDomain
};

// -------------------- Require Statements --------------------
var gulp             = require('gulp'),
	autoprefixer     = require('gulp-autoprefixer'),
	concat           = require('gulp-concat'),
	livereload       = require('gulp-livereload'),
	browserSync      = require('browser-sync').create(),
	newer            = require('gulp-newer'),
	notify           = require('gulp-notify'),
	plumber          = require('gulp-plumber'),
	rename           = require('gulp-rename'),
	sass             = require('gulp-sass'),
	size             = require('gulp-size'),
	uglify           = require('gulp-uglify'),
	watch            = require('gulp-watch'),
	path             = require('path'),
	cssnano          = require('gulp-cssnano'),
	sourcemaps       = require('gulp-sourcemaps'),
	lazypipe         = require('lazypipe'),
	fs               = require('fs');

// -------------------- Notification Icon Detection --------------------
/**
 * Checks to see if a file exists.
 *
 * @param filePath
 * @returns {*}
 */
function fileExists(filePath)
{
	try {
		return fs.statSync(filePath).isFile();
	} catch (err) {
		return false;
	}
}

var iconPath = path.join(__dirname, 'gulp.png');
var icon = fileExists( iconPath ) ? iconPath : null;

// -------------------- Plumber Error Handler --------------------
var plumberErrorHandler = function(err) {
	console.log( 'plumber error! "' + err.message + '"' );
	notify.onError({
		title: config.siteName,
		message: "Error: <%= err.message %>",
		sound: 'Pop'
	});
	this.emit('end');
};

// -------------------- Processors --------------------
//individual scripts (not combined)
var jsIndividualScripts = lazypipe()
	.pipe(plumber, {errorHandler: plumberErrorHandler})
	.pipe(newer, { dest: config.destJS, ext: '.min.js' })
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true})
	.pipe(uglify)
	.pipe(rename, { suffix: '.min' })
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true});

//combined scripts
var jsCombinedScripts = lazypipe()
	.pipe(plumber, {errorHandler: plumberErrorHandler})
	.pipe(newer, config.dest + 'js/scripts.min.js')
	.pipe(concat, 'scripts.js')
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true})
	.pipe(uglify)
	.pipe(rename, { suffix: '.min' })
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true});

//scss compiling
var scssProcessing = lazypipe()
	.pipe(plumber, {errorHandler: plumberErrorHandler})
	.pipe(sass, {outputStyle: ':compact'})
	.pipe(autoprefixer, 'last 2 version')
	.pipe(gulp.dest, config.destCSS)
	.pipe(size, {showFiles: true})
	.pipe(rename, { suffix: '.min' })
	.pipe(sourcemaps.init)
	.pipe(cssnano)
	.pipe(sourcemaps.write, '.')
	.pipe(gulp.dest, config.destCSS)
	.pipe(size, {showFiles: true});

// -------------------- Tasks --------------------
//styles task
gulp.task('styles', function() {
	if ( browserSync.active ) {
		return gulp.src(config.globs.scss)
			.pipe(scssProcessing())
			.pipe(browserSync.reload({stream:true}));
	}
	return gulp.src(config.globs.scss).pipe(scssProcessing());
});

//scripts individual task
gulp.task('scripts-individual', function() {
	return gulp.src(config.globs.js.individual).pipe(jsIndividualScripts());
});

//scripts combined task
gulp.task('scripts-combined', function() {
	return gulp.src(config.globs.js.combined).pipe(jsCombinedScripts());
});

//watch task
gulp.task('live', function() {
	//watch all .scss files
	gulp.watch(config.globs.scss, ['styles']);

	//watch each individual .js file
	watch(config.globs.js.individual).pipe(jsIndividualScripts());

	//watch all combined .js files
	gulp.watch(config.globs.js.combined, ['scripts-combined']);
});

//default task - one time styles and scripts
gulp.task('default', ['styles', 'scripts-individual', 'scripts-combined']);

//start browser-sync server
gulp.task('serve-bs', ['live'], function() {
	browserSync.init(config.browserSync)
});

//start livereload
gulp.task('serve-lr', ['live'], function() {
	livereload.listen();

	//watch for changes on transpired templates, css, and js files
	gulp.watch(config.globs.watched, function(event) {
		gulp.src(event.path)
			.pipe(plumber({errorHandler: plumberErrorHandler}))
			.pipe(livereload())
			.pipe(notify({
					title: config.siteName,
					message: event.type + ': ' + event.path.replace(__dirname, '').replace(/\\/g, '/') + ' was reloaded'
					//,sound: 'Pop'
					, icon: icon
				})
			);
	});
});

## 3) .gitignore
#node files
/node_modules/*

## 4) package.json
{
  "private": true,
  "devDependencies": {
    "browser-sync": "^2.13.0",
    "gulp": "^3.9.1",
    "gulp-autoprefixer": "^3.1.0",
    "gulp-concat": "^2.6.0",
    "gulp-cssnano": "^2.1.2",
    "gulp-livereload": "^3.8.1",
    "gulp-newer": "^1.2.0",
    "gulp-notify": "^2.2.0",
    "gulp-plumber": "^1.1.0",
    "gulp-rename": "^1.2.2",
    "gulp-sass": "^2.3.2",
    "gulp-size": "^2.1.0",
    "gulp-sourcemaps": "^1.6.0",
    "gulp-uglify": "^1.5.4",
    "gulp-watch": "^4.3.9",
    "lazypipe": "^1.0.1",
    "node-sass": "^3.8.0"
  }
}
	// -------------------- Configuration Settings --------------------
	var config = {};

	//basics
	config.siteName = 'Your Site Name';
	config.proxyDomain = 'yoursite.dev';

	//source directory
	config.src = 'source/';

	//destinations
	config.dest = 'public/assets/';
	config.destJS = config.dest + 'js';
	config.destCSS = config.dest + 'styles';

	//globs
	config.globs = {
	scss : config.src + 'scss/*/.scss',
	js : {
	individual : config.src + 'js/individual/*/.js',
	combined : [
	config.src + 'js/combined/libs/*.js',
	config.src + 'js/combined/plugins/*.js',
	config.src + 'js/combined/pluginSubs/*.js',
	config.src + 'js/combined/site/*.js',
	config.src + 'js/combined/site.js'
	]
	},
	watched : [
	config.src + 'craft/templates/*/',
	config.destJS + '/*/.min.js',
	config.destCSS + '/*/.min.css'
	]
	};

	//browser sync
	config.browserSync = {
	files: config.globs.watched,
	proxy: config.proxyDomain
	};

	// -------------------- Require Statements --------------------
	var gulp = require('gulp'),
	autoprefixer = require('gulp-autoprefixer'),
	concat = require('gulp-concat'),
	livereload = require('gulp-livereload'),
	browserSync = require('browser-sync').create(),
	newer = require('gulp-newer'),
	notify = require('gulp-notify'),
	plumber = require('gulp-plumber'),
	rename = require('gulp-rename'),
	sass = require('gulp-sass'),
	size = require('gulp-size'),
	uglify = require('gulp-uglify'),
	watch = require('gulp-watch'),
	path = require('path'),
	cssnano = require('gulp-cssnano'),
	sourcemaps = require('gulp-sourcemaps'),
	lazypipe = require('lazypipe'),
	fs = require('fs');

	// -------------------- Notification Icon Detection --------------------
	/**
	* Checks to see if a file exists.
	*
	* @param filePath
	* @returns {*}
	*/
	function fileExists(filePath)
	{
	try {
	return fs.statSync(filePath).isFile();
	} catch (err) {
	return false;
	}
	}

	var iconPath = path.join(__dirname, 'gulp.png');
	var icon = fileExists( iconPath ) ? iconPath : null;

	// -------------------- Plumber Error Handler --------------------
	var plumberErrorHandler = function(err) {
	console.log( 'plumber error! "' + err.message + '"' );
	notify.onError({
	title: config.siteName,
	message: "Error: <%= err.message %>",
	sound: 'Pop'
	});
	this.emit('end');
	};

	// -------------------- Processors --------------------
	//individual scripts (not combined)
	var jsIndividualScripts = lazypipe()
	.pipe(plumber, {errorHandler: plumberErrorHandler})
	.pipe(newer, { dest: config.destJS, ext: '.min.js' })
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true})
	.pipe(uglify)
	.pipe(rename, { suffix: '.min' })
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true});

	//combined scripts
	var jsCombinedScripts = lazypipe()
	.pipe(plumber, {errorHandler: plumberErrorHandler})
	.pipe(newer, config.dest + 'js/scripts.min.js')
	.pipe(concat, 'scripts.js')
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true})
	.pipe(uglify)
	.pipe(rename, { suffix: '.min' })
	.pipe(gulp.dest, config.destJS)
	.pipe(size, {showFiles: true});

	//scss compiling
	var scssProcessing = lazypipe()
	.pipe(plumber, {errorHandler: plumberErrorHandler})
	.pipe(sass, {outputStyle: ':compact'})
	.pipe(autoprefixer, 'last 2 version')
	.pipe(gulp.dest, config.destCSS)
	.pipe(size, {showFiles: true})
	.pipe(rename, { suffix: '.min' })
	.pipe(sourcemaps.init)
	.pipe(cssnano)
	.pipe(sourcemaps.write, '.')
	.pipe(gulp.dest, config.destCSS)
	.pipe(size, {showFiles: true});

	// -------------------- Tasks --------------------
	//styles task
	gulp.task('styles', function() {
	if ( browserSync.active ) {
	return gulp.src(config.globs.scss)
	.pipe(scssProcessing())
	.pipe(browserSync.reload({stream:true}));
	}
	return gulp.src(config.globs.scss).pipe(scssProcessing());
	});

	//scripts individual task
	gulp.task('scripts-individual', function() {
	return gulp.src(config.globs.js.individual).pipe(jsIndividualScripts());
	});

	//scripts combined task
	gulp.task('scripts-combined', function() {
	return gulp.src(config.globs.js.combined).pipe(jsCombinedScripts());
	});

	//watch task
	gulp.task('live', function() {
	//watch all .scss files
	gulp.watch(config.globs.scss, ['styles']);

	//watch each individual .js file
	watch(config.globs.js.individual).pipe(jsIndividualScripts());

	//watch all combined .js files
	gulp.watch(config.globs.js.combined, ['scripts-combined']);
	});

	//default task - one time styles and scripts
	gulp.task('default', ['styles', 'scripts-individual', 'scripts-combined']);

	//start browser-sync server
	gulp.task('serve-bs', ['live'], function() {
	browserSync.init(config.browserSync)
	});

	//start livereload
	gulp.task('serve-lr', ['live'], function() {
	livereload.listen();

	//watch for changes on transpired templates, css, and js files
	gulp.watch(config.globs.watched, function(event) {
	gulp.src(event.path)
	.pipe(plumber({errorHandler: plumberErrorHandler}))
	.pipe(livereload())
	.pipe(notify({
	title: config.siteName,
	message: event.type + ': ' + event.path.replace(__dirname, '').replace(/\\/g, '/') + ' was reloaded'
	//,sound: 'Pop'
	, icon: icon
	})
	);
	});
	});
	{
	"private": true,
	"devDependencies": {
	"browser-sync": "^2.13.0",
	"gulp": "^3.9.1",
	"gulp-autoprefixer": "^3.1.0",
	"gulp-concat": "^2.6.0",
	"gulp-cssnano": "^2.1.2",
	"gulp-livereload": "^3.8.1",
	"gulp-newer": "^1.2.0",
	"gulp-notify": "^2.2.0",
	"gulp-plumber": "^1.1.0",
	"gulp-rename": "^1.2.2",
	"gulp-sass": "^2.3.2",
	"gulp-size": "^2.1.0",
	"gulp-sourcemaps": "^1.6.0",
	"gulp-uglify": "^1.5.4",
	"gulp-watch": "^4.3.9",
	"lazypipe": "^1.0.1",
	"node-sass": "^3.8.0"
	}
	}