Installing FatKit

Before actually installing and running Grunt there are a few things you need to have installed and running. If you have not already done so, please follow the pre-requisite installation instructions and then return here to continue.


Github

Fatkit on Gitub

The easiest way to get Fatkit up and running with Grunt is to grab a copy from Github. Install the Gitub GUI for either Windows or Mac to get started.

Once you have this installed, open it and in your browser go to the FatKit Gitub repo. Click on the "fork" button found in the top right hand corner, choose your personal account. You now have your own copy of FatKit on your account, linked to the master of FatKit. This allows you to make any changes you see fit to the FatKit codebase, then submit a pull request for Alex to review the changes and merge with the FatKit master.

Learn more about the forking workflow here

Now open your Github GUI, and click the "+" icon located in the top left, switch to the "clone" tab and select your personal account and click on FatKit. You will be asked to choose a location to save this to locally, once you have chosen a location and saved you should see FatKit as a project in you GitHub GUI.

So now you have a local version of the most up-to-date Fatkit. This directory should never be used to build a project, it is to keep an updated copy of FatKit on your computer. Copy this directory to where you would like to build your project, rename it to the project name (e.g. for this example I have used NewProject) and let's get it running with Grunt.

Open your node command prompt (as administrator if you don't like errors) and use it to navigate to the location of NewProject. For example I would do: cd \Documents\Development\Static\NewProject

NOTE To navigate up a directory use ..\ and to the root with cd \


The Big Install

We've created a REALLY easy installation method for you. All you need to do from here is run fatkit.bat (in Windows fatkit.command on a Mac).

NOTE It may take a while to install all dependencies.

Once that has run your project should have opened in Chrome with the default FatKit install. From here feel free to read more information about FatKit.

If there were any issues during install see Alex, Jim or checkout the errors section.


Updating FatKit

Github

To update FatKit after installing via Github please read here.


Running Your Project

On first install of FatKit your project will automatically run the dev task. If you stop this task (with ctrl + c and then typing y and enter) you will have to manually run a task again from the Node.js command line. There are a few builds available so read below on what to run in which scenario.

Builds

Builds are what you run inside the command prompt to actually run Grunt. You can set up as many as you want with different names, for example FatKit comes with a dev, production and check build. These contain different tasks depending on what is needed for that particular build.

For example: the dev build will not run kraken, but the production one will. Depending on what you name your build, this is what you will type into the command prompt to run Grunt. So for example the FatKit production build would be run by typing grunt production.

The four builds FatKit uses are:

  • grunt dev / grunt: outputs sourcemaps, runs browsersync, starts watch task as well as concat, uglify, sass tasks
    (note: you can just type grunt instead of grunt dev for the dev task).

  • grunt check: validates your project by running jshint and postcss stylelint.
    (note: you can just type grunt c instead of grunt check)

  • grunt production: removes console logs, optimises images, copys all minfied files to a www folder as well as concat, uglify, sass tasks. If you set the config variable server.productionDir in grunt/grunt-config.js it will build to that directory instead.
    (note: you can just type grunt pd instead of grunt production)

  • grunt publish: the publish command removes console logs, optimises images and the copies all minified files to a www folder in the root of your current project as well as concatenating, uglifying and tidying everything up ready for a client-facing test site. It will then copy the whole site (including html files etc.) to http://statics.fmdev02.fatoffice.co.uk and put everything in a folder there (as well as creating a screenshot of your site). For this process to run you will need to edit projectName in grunt/grunt-config.js and use a lowercase, hyphenated name (that doesn't already exist).
    (note: you can just type grunt pb instead of grunt production)

    You can also only publish the required type of files you have changed with:
    grunt pb --type={html/js/css/all} (leaving this option off will publsh all by default)


Grunt & Further Reading

Files

Go to where you installed FatKit and in the root of this folder you will notice a few files and folders have been added.

File Description
.gitignore Set certian folders / filetypes / individual files for Github to ignore.
gruntfile.js This is where you set up all your Grunt tasks and where they are called from. Also where your build setups are defined.
package.json This is where Grunts dependencies are kept. You can also set some package details in here; version, author etc.
config/csscomb.json This is the config file for CSS Comb. For more info see tasks.
config/.stylelintrc This is the config file for the PostCss stylelint Grunt task, setup in the gruntfile. For more info see tasks.
config/.jshintrc Config file for the jshint task, designed to relax the strict validation rules. For more info see tasks.
grunt This folder contains all the js files for FatKit's Grunt tasks. They have been separated out so they are easier to manage and other tasks can be added easily. For list of tasks see here.
fatkit.bat Running this once you have all the prerequisites installed and setup, will basically just make Grunt happen, like magic!
checklist.md Before you send anything off for QA / push code live, have you made sure all these are done?

Tasks

NOTE: These are just the core tasks FatKit comes with, if you see any tasks that you would like to add to your build, feel free to add them, try them out and if you think they could benefit other peoples grunt workflow, create a pull request. Likewise if you think any of the tasks below could be improved, improve them and create a pull request.

Task Description
concat Merges all core js files into fatkit.js
uglify Takes the concatenated fatkit.js file and uglifies it into a fatkit.min.js file & uglyifies all component js files.
concurrent Runs as many tasks at the same time as possible.
jshint Lints all unminified js files..
sass Compiles sass files into CSS.
postcss Task for any postcss plugins used. Currently Autporefixing CSS and linting Sass files.
csscomb After sass files are saved, runs config options on it and sorts. This task is currently awaiting a new release and will not work properly until then.
browserSync Live browser refreshing - on steroids.
kraken Release the Kraken.
copy Copies minified CSS, JS, images and font files to a www folder (for easy production updates).
watch A series of tasks set up to be run when you save a file.

Task Details

concat

This task is run to concatenate js files from specified folders or specific files, into one single file.

In grunt-concat.js the task first gets core.js located in the scripts/core folder. This is because core.js contains the defenition for the FatKit function. concat then grabs all .js files in the scripts/core folder. These files are then concatenated into fatkit.js

The dest option sets the destination for all these concatenated files. Which in FatKit is set to fatkit.js

For more options see here

uglify

Now we have concatenated all of our scripts into one file (fatkit.js), we can uglify this file. In the uglify task we also have a number of options we can set.

By default FatKit minifies all js even the files used for the development build. The reason for this is that FatKit creates sourcemap files that sit alongside the minified js. The sourcemap files allow you to debug your js. For production builds, FatKit will also remove any console.log declarations you may have froegotten about.

For production builds the variables of your js files are also mangled, this help save on file size.

FatKit's components are uglified seperately to the core files. This is beacuse they are designed to be used in a modular way, so you would just include them on pages that need to use them. Therefore all the files in the components folder, get uglyfied into their own separate .min.js files. This is also the case with any page specific js you may use on your site. This is kept in the scripts/views folder. These files also get uglyfied into their own .min.js files.

The files options are in the following order 'destination of uglyfied file': ['file to be uglyfied']

For more options see here

The three versions of the uglify task you will see run are:

  • uglify:coreDev / coreLive
  • uglify:viewsDev / viewsLive
  • uglify:componentsDev / componentsLive
concurrent
Runs as many tasks at the same time as possible. Tasks are grouped into similar actions. E.g. Sass, Js etc
jshint

jshint is a javascript linting task, that checks through all the unminified js files used by FatKit and lints them based on rules set in its corresponding config file, located config/jshintrc.

Any errors found will be display in your command prompt

For more options see here

sass

The sass task compiles all your sass files into a CSS file.

Similar to the js uglify task. By default FatKit compresses all CSS. Again sourcemaps are generated for all css files compiled. This will allow you to debug your CSS in development.

In the same way to the JS setup in FatKit. Each component has its own css file created, again this allows you to include components in a more modular fashion.

As with the uglify task the file options are set in the following order 'destination of CSS file': ['file to compile']

For more options see here

The two versions of the uglify task you will see run are:

  • sass:dist - all core CSS, creates your main style.css
  • sass:components - all components CSS, creates individual component css.
postcss

We currenlty have 2 postcss plugins running from this task. Autoprefixer works in the same way the "Autoprefix CSS" checkox does in Prepros, and the second handles the linting of your Sass files.

Autoprefixer

This task autoprefixes your CSS files.

In the options of this task you can set how many browser back you want to go when autoprefixing, for example browsers: ['last 2 versions']

Stylelint

stylelint will look through all of your Sass files and lint against a set of rules defined in the stylelintrc config file. If any errors are found it will list them out in command prompt.

csscomb

csscomb is a CSS sorting task. In FatKit it is set to run on your sass files. When you save a sass file it will look through all the properties and sort it based on the options in the config file associated with it in config/csscomb.json

For the full list of what csscomb will sort on save, please see the config file

NOTE: Due to an issue we have found with the way csscomb re-orders media queries, we have decided to wait for the next realese (4.0) before releasing this task upon FatKit, the release is set for mid summer.

NOTE: This config file will ensure that all sass will be consistent across the company. Its not trying to prescribe how you should be writing your sass, just to set some guidelines and best practices. If you know what to expect when you look at someone else's code it's a lot easier to use.

For more options see here

browserSync

browserSync enables you to set live refresh up on your local machine and also on external devices e.g. your phone / tablet / someone elses computer. browserSync will also sync scrolling across the different devices your site is displayed on a bit like GhostLab does, pretty cool!

FatKit sets browserSync to watch all html, CSS and js files, and when any of these change, load the chnages straight away. If you have any different filetypes e.g. asp then just add them to this list.

When your first run your grunt task, browserSync will open your site in a new tab for you in your default browser. If you take a look in the node command prompt, you will also notice there is an external url given, type this into your external devices and you will see your site.

BrowserSync test URLs

One other great feature of browserSync is that it has UI. You will see these below the front end URL outputs. Put these into your browser and you will be given the browserSync dashboard. This will allow you to remotely debug your site on any external devices it's connected to, outline all elements of your site, basically everything apart from building your site for you.

For more details see here

NOTE: It's worth noting that the script browserSync inserts into your markup is a bit hefty and on yslow comes out at 110kb, when you run the Grunt production build this will not be included.

NOTE: During testing we have noticed that live refreshing .ASP files, can be a bit hit and miss, for the most part it works fine, however sometimes it can cause IIS to throw a 404 error. Just refresh your page again and you should be ok. We have raised a support ticket on the browserSync github page, so will hopefully get a fix in for this in the near future.

kraken

Everyones' favourite image optmiser.

As we have a premium account for Kraken we can use it as a Grunt task, yay!

It's as easy as setting the relative path to your images, setting all file types you want optimising and then setting the destination path to the same as the src, this way it will overwrite your old images.

You can also specify whether Kraken should use lossy optimisation or not.

NOTE: Kraken should only be run when building for production, as we have a 2GB per month limit, we don't want to be optimising our images every time we save a file! Running the newer task in conjunction is also useful, so we only optmise images that have been added / changed.

copy

The copy task is design to speed up the process of pushing the files you edit in your static to the correct place without you having to manually copy and paste the correct ones. The copy task run by the grunt production build will copy your files to both a www folder in the root of your project and also to the assets directory of the CMS files. The copy task run by the grunt publish build will copy your minified assets to the test site address you specify in the relevant grunt cofig and again a www folder.

With the grunt publish build your markup files (any html, asp & php) will also be copied up to your specified test site.

watch

This is the task you may want to setup in accordance with what works best for you / on your project.

In short the watch task contains a number of the tasks detailed above that should be run every time a file is saved, so for example, you will want the csscomb/sass/autprefixer tasks run everytime you save a sass file. So inside the watch task you would add these tasks, and set which order they run in.

For more options see here.

The subs bench

These tasks have no options to setup, they just do their thing in the background.

grunt config

Inside of the grunt tasks folder, there is also a grunt-config file. This contains path variables that FatKit grunt tasks use. For example the file path to the Sass/css/js/images folders. It also contains variables for actual file names e.g. fatkit.js, style.css. These are set so that you can name files site specifically if you wish.

If for any reason you decide to change your file structure, you can simpily change these variables, rather than trawl through all your tasks changing file paths.

newer

For tasks such as kraken and csscomb, we may have a lot of images / sass files to sort / optmise, therefore when we save just one file, we don't want Grunt to run through every file, even though it hasnt changed, enter Grunt newer.

Adding newer before a task will only run that task on files that have changed since it first successfully ran. So the first time you save a sass file, csscomb will sort all your files, then newer will store all these, from then on it will tell csscomb to only run on the specific file you have changed.

NOTE: Newer can also be applied to other tasks you may add in the future, so if it's editing a large number of files, consider using this.

For more details see here.

time grunt

This provides timing of how long each task is taking, so if your Grunt build is running very slowly, cancel the build and a time for each task will be displayed in the command prompt.

For more details see here.

grunt notify

Provides a popup in the bottom right corner of your screen when a Grunt build completes or fails. If it completes you will get a nice message with a (kind of) smiley face, just so you dont miss prepros too much. When a build fails you will see some details of why, look at your command promot for full details. If you're wearing headphones or got sound, you will get an annoying "beep" type sound, dont let that put you off though.

For more details see here.

NOTE: If you just can't handle these notifications getting all up in your grill, you can turn them off in Windows notification settings, by turning off "toast"


Build specific tasks

You can set different options / files to run tasks on depending on which build you are running, so for example if you are running the grunt dev build, you might want the uglify task to run and create fatkit.min.js but not actually minify the code, however when running the production tasks, you would want a minfied file.

If we look at the uglify tasks setup in FatKit, we can see it has been configured differently based on the build you are running.

grunt.config('uglify', {
	dev: {
		// Your dev specific options and files...
	},
	live: {
		// Your production specific options and files...
	}
}

When defining tasks to run in your builds, you can then run the tasks specific to that build. For example the dev build grunt.registerTask('dev', ['uglify:dev']);


Globbing Patterns

This refers to the way you reference files in your paths set in tasks e.g. assets/styles/sass/**/*.scss.

For more details here's a stack overflow.


Errors

If your Grunt build is failing, check the command prompt as the error details given in here are usually pretty useful. If it's a syntax issue, it provides lines line number details, plus if thats not obvious enough it even adds some arrows in to show you what's wrong.

If it's an issue with a task normally the build will fail. However, if it's something that you are aware of, or want to ignore for now, in the tasks options you can set force: true. This will allow the build to complete even if the task fails. Again the details of why the task has failed are usually pretty good, usually it's an issue with file paths you have specified, or something you may not have installed properly.

Any jshint / scss-lint errors will also output into the command prompt.

NOTE Running grunt -v will give you extensive logging.


FAQ's

What if I can't get Grunt running properly, or I don't like using the command prompt?

Use prepros

Why is the watch task devouring all my memory/cpu?

Likely because of an enthusiastic pattern trying to watch thousands of files. Such as '**/*.js' but forgetting to exclude the node_modules folder with '!**/node_modules/**'. Try grouping your files within a subfolder or be more explicit with your file matching pattern.