Using desktop software
Compiling

There are tons of different applications and extensions available for LESS compiling, i prefer to use Koala application for Mac. It doesn't have hundreds of different settings, but it does exactly what i need, fast and effectively.

By default, Limitless template uses 4 separate compiled CSS files - bootstrap.css, core.css, colors.css and component.css. As you may notice, files have same names as 4 main less files located in assets/less/ folder root. Actually these 4 css files are compiled main less files. In fact, to compile CSS files, use only these 4 main less files:

  • bootstrap.less - Bootstrap core
  • core.less - Bootstrap core overrides
  • components.less - all template components and plugins, except Bootstrap ones
  • colors.less - color system (optional)

The reason why they were divider into 4 files is IE doesn't support css files with 10k+ properties. If you don't use some of them or don't care much about IE, feel free to combine those 4 files into 2, try to keep bootstrap.css separately. Color system is completely optional, if you've setup your primary theme, you can exclude this file and re-compile your CSS.

Screenshot - colors.less file

Using Gulp
Overview

Starting from version 1.2 Limitless includes gulpfile.js and package.json files for Gulp task runner. By default it contains basic tasks that are already configured. If you know how to use it - go for it, if you don't - here is a simple instruction how you can setup everything and get your tasks done right.

Step 1 - Install Node.js

First - we need our most important requirement, Node. To install Node - simply visit http://nodejs.org and then click that big green “Install” button. Once your download completes, run that application and you should be all ready to go. The Node installer also includes npm, which we will come back to a little later.

Step 2 - Command line

Now, you may not be very familiar with your command-line interface (Terminal for OSX, Command Prompt for Windows) but you should be! It may seem intimidating at first, but once you get the hang of it you will have the ability to run many different command line applications such as Sass, Yeoman and Git. All of which are very useful tools that your workflow could benefit from!

As a quick example, open up your command line and we will throw a couple commands at it to ensure that Node is properly installed. Type that and then hit enter and you should get a response on the next line with the version number of Node that you have installed:

node -v

Now, let’s do the same for npm:

npm -v
If you didn’t get a response, then it may mean that Node didn’t install correctly or you may need to restart your command line application. If this still isn’t working after restarting, then simply jump back up the top and try the first step again.
Step 3 - Install Gulp

You’ve met your command-line and you know how to talk to it - you even know your way around your file system. Now, it’s time to get to the good stuff. Let’s meet npm and install gulp!

NPM stands for Node Package Manager and it is a command line tool that will allow you to install additional Node packages to your projects. It even comes with a nifty site that allows you to browse and search through all of the available packages.

In your command-line application, type:

sudo npm install -g gulp

Let’s quickly break this down.

  1. sudo is the command to grant you administrator access so you can properly install files globally. It will prompt you for your computer password before it continues. This is usually needed for global installation, but should not be required when installing plugins in your local project directory.
  2. npm is the application we are using to install our package.
  3. We are running the install command on that application.
  4. The -g is an optional flag used to signify that we want to install this package globally so that any project can use it.
  5. And finally, gulp is the name of the package we would like to install.

Once that has run it’s course check your command-line to ensure that there are no error messages. If there are none to be seen, then congratulations! You just installed gulp! Just to double check, let’s refer back to our versioning commands we used above for Node and npm.

gulp -v

Like before, this should return the version number on the next line of your command-line.

Next, we also need to install gulp locally.

npm install --save-dev gulp

Now that we have met our command-line interface and know how to communicate with it, our next step will be navigating it. Luckily, it only takes two commands to change directories and take a look at what is inside them. These commands are ls (or dir, for Windows) to list what is in a directory and cd to change directories.

Once you are comfortable with the ls and cd commands, we need to navigate to our project folder. This will likely be different for each person, but as an example this is what I would type to navigate to my local project:

// Path to Limitless layout folder
cd /Applications/MAMP/htdocs/Limitless/Layout\ 1/LTR
Step 5 - Running tasks

Once gulp is installed we have to give it some instruction so it knows what tasks for perform for us. But, first, we need to figure out exactly what tasks we need to run in our project.

Gulp plugins you'll need:

  • gulp-jshint - lint JavaScript
  • gulp-less - Less files compiler
  • gulp-clean-css - CSS compression
  • gulp-concat - concatenate our JavaScript
  • gulp-uglify - minify files
  • gulp-rename - rename files

Install required plugins:

npm install gulp-jshint gulp-less gulp-clean-css gulp-concat gulp-uglify gulp-rename --save-dev

If you are getting permissions errors installing these plugins you may have some issues with the permissions in your local project directory. You can prepend those commands with sudo, but it is not advised as it can lead to more problematic issues later. The best course of action is to ensure the permissions of your directories are setup properly.

it’s very important to mention that gulp only has 5 methods. These methods are as follows: task, run, watch, src, and dest. These are all you will need to write your tasks.

Gulp file

// Include gulp
var gulp = require('gulp'); 


// Include our plugins
var jshint = require('gulp-jshint');
var less = require('gulp-less');
var minifyCss = require('gulp-clean-css');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');


// Lint task
gulp.task('lint', function() {
    return gulp
        .src('assets/js/core/app.js')                 // lint core JS file. Or specify another path
        .pipe(jshint())
        .pipe(jshint.reporter('default'));
});


// Compile less files of a full version
gulp.task('less_full', function() {
    return gulp
        .src('assets/less/_main_full/*.less')         // locate /less/ folder root to grab 4 main files
        .pipe(less())                                 // compile
        .pipe(gulp.dest('assets/css'))                // destination path for normal CSS
        .pipe(minifyCss({                             // minify CSS
            keepSpecialComments: 0                    // remove all comments
        }))
        .pipe(rename({                                // rename file
            suffix: ".min"                            // add *.min suffix
        }))
        .pipe(gulp.dest('assets/css'));               // destination path for minified CSS
});


// Compile less files of starter kit
gulp.task('less_starters', function() {
    return gulp
        .src('assets/less/_main_starters/*.less')     // locate /less/ folder root to grab 4 main files
        .pipe(less())                                 // compile
        .pipe(gulp.dest('starters/assets/css'))       // destination path for normal CSS
        .pipe(minifyCss({                             // minify CSS
            keepSpecialComments: 0                    // remove all comments
        }))
        .pipe(rename({                                // rename file
            suffix: ".min"                            // add *.min suffix
        }))
        .pipe(gulp.dest('starters/assets/css'));      // destination path for minified CSS
});


// Minify template's core JS file
gulp.task('minify_core', function() {
    return gulp
        .src('assets/js/core/app.js')                 // path to app.js file
        .pipe(uglify())                               // compress JS
        .pipe(rename({                                // rename file
            suffix: ".min"                            // add *.min suffix
        }))
        .pipe(gulp.dest('assets/js/core/'));          // destination path for minified file
});


// Watch files for changes
gulp.task('watch', function() {
    gulp.watch('assets/js/core/app.js', [             // listen for changes in app.js file and automatically compress
        'lint',                                       // lint
        //'concatenate',                              // concatenate & minify JS files (uncomment if in use)
        'minify_core'                                 // compress app.js
    ]); 
    gulp.watch('assets/less/**/*.less', ['less_full', 'less_starters']);    // listen for changes in all LESS files and automatically re-compile
});


// Default task
gulp.task('default', [                                // list of default tasks
    'lint',                                           // lint
    'less_full',                                      // full version less compile
    'less_starters',                                  // starter kit less compile
    'minify_core',                                    // compress app.js
    'watch'                                           // watch for changes
]);

Now, let’s break this down and review what each part does.

Core & plugins
// Include our plugins
var jshint = require('gulp-jshint');
var less = require('gulp-less');
var minifyCss = require('gulp-clean-css');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');
This includes the gulp core and plugins associated with the tasks that we will be performing. The available tasks are lint, less, compress and default.
Link task
// Lint Task
gulp.task('lint', function() {
    return gulp
        .src('assets/js/core/app.js')                 // lint core JS file. Or specify another path
        .pipe(jshint())
        .pipe(jshint.reporter('default'));
});
Lint task checks any JavaScript file in our js/ directory and makes sure there are no errors in our code.
Less task
// Compile less files of a full version
gulp.task('less_full', function() {
    return gulp
        .src('assets/less/_main_full/*.less')         // locate /less/ folder root to grab 4 main files
        .pipe(less())                                 // compile
        .pipe(gulp.dest('assets/css'))                // destination path for normal CSS
        .pipe(minifyCss({                             // minify CSS
            keepSpecialComments: 0                    // remove all comments
        }))
        .pipe(rename({                                // rename file
            suffix: ".min"                            // add *.min suffix
        }))
        .pipe(gulp.dest('assets/css'));               // destination path for minified CSS
});
The less task compiles any of our Less files in our less/ directory into .css and saves the compiled .css file in our css/ directory. By default ess files compile into nodmal and minified css files. You can remove a few lines to get minified files only. There are 2 tasks for less compilation - 1 for main files and 1 for starter kit.
Compress task
// Concatenate & Minify JS
gulp.task('minify_core', function() {
    return gulp
        .src('assets/js/core/app.js')                 // path to app.js file
        .pipe(uglify())                               // compress JS
        .pipe(rename({                                // rename file
            suffix: ".min"                            // add *.min suffix
        }))
        .pipe(gulp.dest('assets/js/core/'));          // destination path for minified file
});
The minify_core task minifies core template's JavaScript file in our js/core directory and saves the ouput to to the same directory with .min suffix.
Watch task
// Watch Files For Changes
gulp.task('watch', function() {
    gulp.watch('assets/js/core/app.js', [             // listen for changes in app.js file and automatically compress
        'lint',                                       // lint
        'minify_core'                                 // compress app.js
    ]); 
    gulp.watch('assets/less/**/*.less', ['less_full', 'less_starters']);    // listen for changes in all LESS files and automatically re-compile
});
The watch task is used to run tasks as we make changes to our files. As you write code and modify your files, the gulp.watch() method will listen for changes and automatically run our tasks again so we don't have to continuously jump back to our command-line and run the gulp command each time.
Default task
// Default tasks
// Default task
gulp.task('default', [                                // list of default tasks
    'lint',                                           // lint
    'less_full',                                      // full version less compile
    'less_starters',                                  // starter kit less compile
    'minify_core',                                    // compress app.js
    'watch'                                           // watch for changes
]);
Finally, we have our default task which is basically a wrapper to our other tasks. This will be the task that is ran upon entering gulp into the command line without any additional parameters.
Running tasks:

Now, all we have left to do is run gulp. Switch back over to your command-line and type:

gulp

This will call gulp and run everything we have defined in our default task. So, in other words It’s the same thing as running:

gulp default

Additionally, we don’t have to run the default task. We could run any of the tasks we defined at any time. Simply call gulp and then specify the task you would like to run directly afterward. For example, we can run our sass task manually at any time like so:

gulp less

or to watch changes and re-run task when file changes:

gulp watch
Credit
Many thanks to Travis Maynard for the great article Getting started with Gulp.