Why Gulp?

If you have ever worked with Magento you are probably aware of it’s complexity and deep folder structure whether it is backend or front-end development. In such a demanding system you will probably want that one tool that will make your Magento development easier. There are actually two that work great together.

Have you ever asked yourself how it would be to have a task runner that will do jobs in the background for you while you develop?

How about having css auto-compiled from smaller less or sass chunks of code and being able to see which sass or less file is in use for some inspected element from your browser?

How about javascript concatenating, auto reloading all of your web browsers across multiple devices on JS files change or auto injecting your compiled css so you can instantly see changes even without reloading your browser? The answer is Gulp.

Install Gulp

To install Gulp, you’ll need to have npm – Node.js package manager. Being a part of Node.js the best way is to install Node.js itself.

It’s a powerful tool that allows you to execute JavaScript system wide.

After Node.js is installed, we need to install Gulp globally with the following command:

sudo npm install -g gulp

Magento Gulp setup

Next step is to set up Gulp environment into our Magento skin/frontend/waterlee-boilerplate/default folder*.

The files we will need to create are package.json and gulpfile.js.

*Using here our own Magento theme as an example.

package.json

This file stores information about our project and gulp dependencies we are using.
You can create it with npm init command and it will walk you through creating a package.json file.

Example with dependencies only:

As it’s shown, there are npm package names with version numbers. If we already have this file from repo, it’s enough to type sudo npm install and Node package manager will automatically install all packages with correct version numbers.

You can easily install additional packages with sudo npm install package_name   – – save – devoption and latest version package will be installed and added to package.json under “devDependencies”.

Typical version ranges: ~  ^  *   >

• * Matches any version
• ^ Compatibile with version
• ~ Approximately equivalent to version
• > Must be greater than version

For more information about version ranges and package.json file you can check npm help json command.

After running npm, you should see node_modules folder created inside your project folder. This is the folder which contains our packages installed locally.

Up to this point, we’ve installed Gulp globally and locally. The fact is that we don’t need Gulp globally installed to run it inside our project. We could call it from node_modules folder like this: ./node_modules/.bin/gulp task_name and it will work, but having it globally installed we can run it from anywhere, so we run gulp with gulp task_name command only, or better, if we want default task, we need to type just gulp (More about gulp tasks in gulpfile.js). Easier, right?

gulpfile.js

This is our Magento Gulp configuration file in which we will create tasks needed for our project. Example below demonstrates some basic tasks just to show simplicity of Gulp configuration.

First we need to declare variables for required packages (gulp & gulp-sass). Further, we define task with gulp.task followed by task name and function which needs to return something.

In our Sass-task example, we need to set source destination with gulp.src and then pipe our source files through gulp-sass package with pipe method. At the end we pipe processed file to css destination folder which we set with gulp.dest.

That’s it. Try to run gulp sass command now and our Sass task will create styles.css in css folder.

Next task is used for watching files and the last one is default Gulp task in which we specified all the tasks which will be run.

So if we run gulp from command line, the default task will be launched in which we have “sass” and “watch” tasks. Note that default task does not end like SASS task because we have “watch” in it. It watches for our changes in SCSS files and then makes our CSS file, instantly, that’s how fast Gulp is.

Packages can be found at npmjs.com with it’s basic usage described. You can also check the “.gulpfile” from our waterlee-boilerplate to get the idea.

BrowserSync

Here comes the interesting part where you can really control your design process through all browsers and devices.

If you haven’t seen it in action, here’s a quick screencast from their website:

We will expand our previous example just to show BrowserSync in action.

As it’s shown, we added a new variable because browser-sync package is required here.

Next, browser-sync task is created. Proxy is specified (our Magento installation folder) and BrowserSync port. It can be seen that we piped “browserSync.reload” in SASS task with “stream:true” option. This way we’ll have auto injecting css in our browser(without reloading whole page).

The last thing is to add browser-sync task to the default one, so we finally have a pretty good gulp default task which should watch for our sass changes, compile css and inject it into the browser. Note that when you run a gulp command, BrowserSync will list local and external addresses from where you can access your Magento site.

So if you want to test your site on mobile or maybe you have a virtual box with windows where you need to test your site on IE just go to external address with a port you specified in your gulpfile.js. Besides injecting changes, BrowserSync will emulate scrolling, clicks etc…across your devices. Magic!

Quick install

Here is a quick Magento Gulp setup of example which is covered in this blog post:

1. Install Node.js. You can download installer package or build it from source.
2. Install Gulp globally with sudo npm install -g gulp command.
3. Set up Magento Gulp environment by downloading package.json and gulpfile.js into your skin/frontend/custompackage/customtheme folder. Eventually you will want to change source scss and destination css folder if you have different folder structure then our project. Same goes for magento folder name in browser-sync task.
4. Inside skin/frontend/custompackage/customtheme folder run sudo npm install command to install node modules locally.
5. Run gulp command.
6. That’s it! You can start playing with gulp tasks.