Q SASS Taskrunner Guide

README.md

Q Taskrunner Setup

To install from scratch:

• Go to the q-theme-x folder folder of the project in terminal
• Pull the latest updates from the github of the plugin - this will also:
• update the .gitignore to ignore /nodemodules
• Add the Gruntfile.js file
• Add the package.json file

Install global dependencies:

First check to see if you have the dependencies already installed

$ node -v
$ npm -v
$ sass -v

If you get a "Command not found" error instead of a version number, you will need to install the global dependency that you are missing. These should all be installed in a global fashion, as they will be needed on every repo that compiles CSS.

1. Install Node: https://www.taniarascia.com/how-to-install-and-use-node-js-and-npm-mac-and-windows/
2. Once you install node, you should have NPM, check with the npm -v command again. If there is a problem go here: https://www.npmjs.com/get-npm
3. @TODO - Ruby no longer required

Run Grunt

Now that you have your dependencies, you should be able to run everything. Just run npm install and it will install the package.json

Everything should build, and if it looks good you can run the grunt command. If it runs without issues you are ready to compile your sass modules:

$ npm install
$ grunt

Once you are ready to edit your SCSS/SASS modules run

$ grunt watch

and you will compile your modules in real-time. Thanks!

License

MIT

Gruntfile.js

'use strict';
module.exports = function(grunt) {

	grunt.initConfig({

		// ------- configuration ------- ##

		// common SCSS root for easier SCSS @use / @forward / @incuse usage ##
		includePaths: [
			'./library/theme/scss/' // common SCSS root ##
		],

		// sass controller file ##
		src: 'library/theme/scss/q.scss.theme.scss', 

		// main destination file ##
		dest: 'library/theme/css/q.scss.theme.css', 

		// minified destination file ##
		dest_min: 'library/theme/css/q.scss.theme.min.css', 

		// object of files to clean up pre-compile ##
		clean_dest: [ 
			'library/theme/css/q.scss.*.css', // regex to find all generated css files ##
			'library/theme/css/q.scss.*.map', // regex to find all generated map files ##
		],

		// scss files to watch ## 
		watch_scss: [
			'library/theme/scss/view/*.scss', // regex to track all Template files ##
			'library/theme/scss/ui/*.scss', // regex to track all UI files ##
			'library/theme/scss/q/*.scss', // regex to track all config files ##
			'library/theme/scss/bootstrap/*.scss', // regex to track ,main Bootstrap include ##
		],

		// php files to watch ## 
		watch_php: [ 
			'library/theme/view/*.php', // main view [template] folder ##
			'library/theme/ui/*.php' // ui folder ##
		],

		// ------- end config ------- ##

		// clean up old compilled files ##
		'clean': {
			'dist': 
				'<%= clean_dest %>'
		},

		// SASS compiller ##
		'dart-sass': {
			'target': {
				'options': {
					'outputStyle'	: 'expanded',
					'sourceMap'		: true,
					'includePaths'	: '<%= includePaths %>',
					'lineNumber'	: true,
				}, 
			  	'files': {
					'<%= dest %>': '<%= src %>'
			  	}
			}
		},

		// watch task ##
		'watch': {
			// track changes to scss src files ##
			'sass': {
				'options': {
					'livereload': 1337, // dedicated port for live reload ##
				},
				'files': 
					'<%= watch_scss %>'
				,
				'tasks': [
					'default',  // post processing formating ##
				]
			},
			// track changes to specific PHP templates ##
			'php': {
				'options': {
					'livereload': 1337,
				},
				'files': 
					'<%= watch_php %>'
				,
				'tasks': [
					'php' // no tasks yet ##
				]
			},
		},

		// post processing formating ##
		'postcss': {
			'options': {
				'map': true, // inline sourcemaps
				'processors': [
					// add fallbacks for rem units ##
					require('pixrem')(), 
					// add vendor prefixes -- options defined in package.json 'browserslist' ##
					require('autoprefixer')(),
				]
			},
			'dist': {
				'src': '<%= dest %>',
				'dest': '<%= dest %>',
			},
			'minify': {
			 	'options': {
			 		'processors': [
			 			require('cssnano')() // minifies ##
			 		]
			 	}, 
				'src': '<%= dest %>',
				'dest': '<%= dest_min %>',
			}
		},

  	});

	// Load Tasks ##
	grunt.loadNpmTasks('grunt-contrib-clean'); // Clean up Tasks ##
	grunt.loadNpmTasks('grunt-contrib-watch'); // Watcher ##
	grunt.loadNpmTasks('grunt-postcss'); // Post Processing ##
	grunt.loadNpmTasks('grunt-dart-sass'); // DART SASS ##

	// Register Tasks ##
	grunt.registerTask( 'default', [
		'clean', // clean up old compilled files ##
		'dart-sass', // Dart SASS ##
		'postcss', // post processing formating ## ##
	]);

	// Watch Task ##
	grunt.registerTask( 'php', [
		// No specific tasks, just live reload ## 
	]);

};

package.json

{
	"name": "q-theme-sass-taskrunner",
	"version": "1.0.0",
	"description": "Q : Theme SASS Taskrunner",
	"author": "Q Studio",
	"homepage": "https://qstudio.us",
	"repository": {
		"type": "git",
		"url": "qstudio/50444e2589d7c77ce7c62c0b75d422d3"
	},
	"license": "MIT",
	"engines": {
		"node": ">= 10.16.1"
	},
	"keywords": [
		"grunt, sass"
	],
	"dependencies": {
		"chalk": "^2.1.0",
		"diff": "^3.0.0",
		"pixrem": "^5.0.0",
		"postcss": "^6.0.11"
	},
	"devDependencies": {
		"autoprefixer": "^9.7.6",
		"cssnano": "^4.1.10",
		"grunt": "~1.0.3",
		"grunt-contrib-clean": "~2.0.0",
		"grunt-contrib-nodeunit": "^2.0.0",
		"grunt-contrib-sass": "~1.0.0",
		"grunt-contrib-watch": "~1.1.0",
		"grunt-dart-sass": "^1.1.3",
		"grunt-file-append": "0.0.7",
		"grunt-postcss": "^0.9.0",
		"load-grunt-tasks": "^3.1.0",
		"postcss-scss": "^1.0.2",
		"sass": "*",
		"time-grunt": "^1.1.0"
	},
	"browserslist": [
		"last 5 versions",
		"> 1%",
		"IE 10",
		"Edge 16"
	]
}