Grunt Overview

Grunt is the JavaScript task runner with the largest ecosystem. You can use Grunt to automate just about anything with a minimum of effort. We provide Grunt tasks for the most important aspects of customizing our templates.


Prerequisites

Make sure you have followed the Grunt installation steps for your operating system.

Linux / Mac OS X

Windows

Additionaly, when running on Windows operating systems, do the following:

  1. remove the provided Gruntfile.js from the root directory of the project, if it already exists - it's a soft linux symlink and chances are the contents of this file is just a pointer to the real file which is located in lib/grunt/Gruntfile.js
  2. copy lib/grunt/Gruntfile.js in place of the file you removed at step 1.
  3. When using Windows, make sure all the commands in this documentation are executed from either the Terminal builtin with SourceTree or a MSYS terminal. Don't use cmd.exe, it won't work! See installation on Windows.

Notes

Substitute $THEME_NAME where ever you see it thoughout the documentation instructions with a valid theme name. You can see the available themes by looking at the first level directories within src/html/themes.


Build

Unlike Gulp, where we have a stream based build pipeline, Grunt provides a file based build system. Nonetheless, it connects files together across a number of processing steps, defining dependencies and which results in the final assets that get used by the application.

Build paths

A build path is the destination directory where our final assets are placed after going through the build process. The build path is established with the --dist path/to/build CLI option.


Concatenated files and bundles

See Concatenated files and bundles from Gulp.

Build with concatenated files and bundles

grunt --theme $THEME_NAME build:d

This is the fastest build task and has the following main characteristics:

  1. Cleans the theme's build path (removes everything under $BUILD_PATH/$THEME_NAME/).

  2. Does NOT generate minified assets.

    You can enable minification for both CSS and JavaScript:

    grunt --theme $THEME_NAME build:d --minify true
    

    And with source maps:

    grunt --theme $THEME_NAME build:d --minify true --debug true
    
  3. Compiles Less files into CSS:

    • src/less/themes/$THEME_NAME/app.less into $BUILD_PATH/$THEME_NAME/css/app/app.css (required)
    • src/less/themes/$THEME_NAME/main.less into $BUILD_PATH/$THEME_NAME/css/app/main.css
    • src/less/themes/$THEME_NAME/vendor/*.less into $BUILD_PATH/$THEME_NAME/css/vendor/*.css
  4. Bundles application JavaScript with Browserify:

    • src/js/themes/$THEME_NAME/app.js into $BUILD_PATH/$THEME_NAME/js/app/app.js (required)
    • src/js/themes/$THEME_NAME/main.js into $BUILD_PATH/$THEME_NAME/js/app/main.js
    • executes browserify tasks defined in .build/browserify.json
    • excluding tasks for which the build key starts with app/* (which are ignored)
  5. Compiles Swig template files into HTML:

    • src/html/themes/$THEME_NAME/**/*.html into $BUILD_PATH/$THEME_NAME/**/*.html
  6. Copies files, in the following order:

    1. src/images/common/* into $BUILD_PATH/$THEME_NAME/images/* - images stored here will end up in every theme
    2. src/images/themes/$THEME_NAME/* into $BUILD_PATH/$THEME_NAME/images/* - theme specific images
    3. executes copy tasks defined in .build/copy-*/copy.*.json (in path alphabetical order)
    4. executes copy tasks defined in .build/copy.json
  7. Concatenates files, in the following order:

    1. executes concat tasks defined in .build/concat-*/concat.*.json (in path alphabetical order)
    2. executes concat tasks defined in .build/concat.json
    3. excluding tasks for which the build key starts with js/app/* (which are ignored)

Note that the execution order of different tasks is important.


Separated libraries

See Separated libraries from Gulp.

Build with separated libraries

We definitely don't recommend this, but we won't stop you either. Here's how you can do it:

grunt --theme $THEME_NAME build:dm

Which is the same as:

grunt --theme $THEME_NAME build:d

But, with the following additional tasks:

  1. Compiles separated Less modules to CSS:

    • src/less/theme/$THEME_NAME/app/*.less into $BUILD_PATH/$THEME_NAME/css/app/*.css
  2. Bundles separated JavaScript modules with Browserify:

    • executes browserify tasks defined in .build/browserify.json
    • including tasks for which the build key starts with app/* (which are ignored with build:d)
  3. Concatenates separated JavaScript files which don't make use of Browserify and require:

    • executes concat tasks defined in .build/concat-app/concat.*.json
    • executes concat tasks defined in .build/concat.json
    • including tasks for which the build key starts with js/app/* (which are ignored with build:d)

Additionally, you can instruct Swig when it compiles into HTML, to automatically load the separated files instead of the bundles (so the final HTML output of your application will look similar to this example):

grunt --theme $THEME_NAME build:dm --bundle false

Watch

grunt --theme $THEME_NAME

See Watch from Gulp.


Tasks

While we already introduced the most important tasks of the grunt workflow, build:d, build:dm and watch, there are several other tasks that are actually used by the build tasks themselves and that you can also use when you see fit.


Browserify tasks

browserify

grunt --theme $THEME_NAME browserify

browserify-modules

grunt --theme $THEME_NAME browserify-modules

Code validation tasks

jshint

grunt --theme $THEME_NAME jshint

JavaScript compression tasks

uglify:all

grunt --theme $THEME_NAME uglify:all

uglify:theme

Minifies the following JavaScript files:

grunt --theme $THEME_NAME uglify:theme

uglify:modules

Minifies all JavaScript files from $BUILD_PATH/$THEME_NAME/js/app/*.js to $BUILD_PATH/$THEME_NAME/js/app/*.min.js.

Except:

grunt --theme $THEME_NAME uglify:modules

uglify:main

Minifies JavaScript from $BUILD_PATH/$THEME_NAME/js/app/app.js to $BUILD_PATH/$THEME_NAME/js/app/app.min.js.

grunt --theme $THEME_NAME uglify:main

CSS compression tasks

cssmin:vendor

grunt --theme $THEME_NAME cssmin:vendor

cssmin:theme

Minifies the following CSS files:

grunt --theme $THEME_NAME cssmin:theme

cssmin:modules

grunt --theme $THEME_NAME cssmin:modules

cssmin:skins

grunt --theme $THEME_NAME cssmin:skins

cssmin

Runs the following cssmin tasks:

grunt --theme $THEME_NAME cssmin

Copy tasks

copy:images_common

grunt --theme $THEME_NAME copy:images_common

copy:images_theme

grunt --theme $THEME_NAME copy:images_theme

copy

Runs the following copy tasks:

grunt --theme $THEME_NAME copy

copy-build

Runs the following copy tasks:

  1. copy:images_common
  2. copy:images_theme
  3. executes copy tasks defined in .build/copy-*/copy.*.json (in path alphabetical order)
  4. executes copy tasks defined in .build/copy.json
grunt --theme $THEME_NAME copy-build

Concatenation tasks

concat

  1. executes concat tasks defined in .build/concat-*/concat.*.json (in path alphabetical order)
  2. executes concat tasks defined in .build/concat.json
  3. excluding tasks for which the build key starts with js/app/* or css/app/* (which are ignored)
grunt --theme $THEME_NAME concat

concat-modules

  1. executes concat tasks defined in .build/concat-*/concat.*.json (in path alphabetical order)
  2. executes concat tasks defined in .build/concat.json
  3. ONLY tasks for which the build key starts with js/app/* or css/app/*
grunt --theme $THEME_NAME concat-modules

Clean tasks

clean:html

grunt --theme $THEME_NAME clean:html

clean:dist

grunt --theme $THEME_NAME clean:dist

clean:modules

grunt --theme $THEME_NAME clean:modules

clean:skins

grunt --theme $THEME_NAME clean:skins

clean

Runs all the following clean tasks:

grunt --theme $THEME_NAME clean

HTML tasks

swig

grunt --theme $THEME_NAME swig

prettify:theme

grunt --theme $THEME_NAME prettify:theme

Less tasks

less:theme

grunt --theme $THEME_NAME less:theme

less:modules

grunt --theme $THEME_NAME less:modules

less:vendor

grunt --theme $THEME_NAME less:vendor

less:skins

grunt --theme $THEME_NAME less:skins

less

Runs all the following less tasks:

grunt --theme $THEME_NAME less

CSS vendor prefixes

Parse CSS and automatically add vendor prefixes to CSS rules for the last 4 versions of all browsers.

autoprefixer:theme

Automatically add vendor prefixes to:

grunt --theme $THEME_NAME autoprefixer:theme

autoprefixer:modules

Automatically add vendor prefixes to $BUILD_PATH/$THEME_NAME/css/app/*.css.

Except:

grunt --theme $THEME_NAME autoprefixer:modules

autoprefixer:skins

grunt --theme $THEME_NAME autoprefixer:skins

autoprefixer

Runs all the following autoprefixer tasks:

grunt --theme $THEME_NAME autoprefixer

See also