Introduction to Gulp.js 1: Intro and Setup

Introduction to Gulp.js 1: Intro and Setup

My website is running Jekyll now since the beginning of 2014. But I wasn’t happy with my build and development process. I started with Rake tasks and chose later Grunt.js as my build system, but parts of the process were left in Ruby. I used Compass a lot, and Jekyll Assets was handling my versioning. But Grunt.js and the Jekyll Asset Pipeline didn’t play well together. Then a new solution came along: Gulp.js.

What to expect from this Tutorial

This is the first part in a series of posts where I describe my whole development and build process step-by-step from start to finish. I am sick of all these Hello World tutorials spreading around the Internet, describing the basics and don’t show a whole process, going deeper, or sharing things learned during the process.

I’ll describe everything step-by-step and provide specific version numbers for modules, to make sure they will run on your computer. If you have problems, feel free to compare your code to the finished GitHub repository. Each tutorial builds on the things done before. If you need a specific thing, better look at the final codebase. You’ll learn how I created my complete development and build process, which I use on this website and my Ninja & Ninjutsu website. The source of both websites can be found on my GitHub account.

When I started with Gulp.js, I fortunately stumbled upon a GitHub project called gulp-starter blendid, that helped me a lot to structure my code and understand Gulp.js. My process is partly derived from this fantastic project.

What is Gulp.js?

Gulp.js is the streaming build system and its main focus is speed, efficiency, and simplicity. Where Grunt.js uses a lot of configuration with the process hidden in plugins, Gulp.js uses a simple and minimal API. You code your build process by yourself and use JavaScript as the language. You don’t have to program everything by yourself, there are nearly 800 plugins ready for Gulp.js. But even more, Node.js modules can be used to build the perfect build and development process for your needs.

Why do I want this at all?

As a front-end developer or web designer you will likely need plenty of things to build a modern website: a development server, a preprocessor for your Sass, Less or Stylus files, automation to bundle your JavaScript, tools to optimize your code, to compress, compile or move things around. And if you change something, you want your files to update automatically, or refresh the browser. You don’t want to do this manually, do you?

It’s 2014, and we don’t copy our files per drag-and-drop to a server via an FTP program, reload our browser by hitting continuously F5 or crunch our images for a smaller file size manually.


Gulp and all plugins are written in JavaScript and use the Node.js® platform. You don’t have to know Node.js (but it will help a lot), but basic JavaScript skills are required to follow along. For this tutorial, you need to install Node.js on your computer. This can be done by installing the package on the Node.js website. Advanced users may install Node.js with their favorite package installer (Homebrew, nvm, or similar).


As with Grunt.js, all you need to start is the main file. In Gulp.js, this file is called gulpfile.js. The first thing I learned from gulp-starter was to write my project in small parts and don’t use a large monolithic file with everything in it. This way I can share my Gulp.js files with other projects or pass individual tasks around.

My base gulpfile.js is short:


var requireDir = require("require-dir");

// Require all tasks in gulp/tasks, including subfolders
requireDir("./gulp/tasks", { recurse: true });

All this task is doing is loading all tasks that live in ./gulp/tasks or in any subfolder.

First Things First

The first thing to do is to install the required Node module require-dir. To reinstall all my node modules later, I will need to have a file where this information is saved.

You may use the installation helper by typing the command npm init. But I find it faster to create a new file package.json and fill it with these values:


  "name": "gulp-build",
  "version": "0.0.1",
  "description": "The build process of my website with Gulp.js",
  "private": true

Now I can install Node modules and save them to this file for later reinstallation. Go ahead and install require-dir:

$ npm install --save-dev require-dir@0.3.0

This will install our first Node module and place it into a folder with the name node_modules. Don’t delete this folder, or you will have to reinstall all modules again. This can be done later with npm install. The command will install all modules in the package.json file.

My Jekyll website lives in a folder called app. All my tasks will be placed in a folder with the name gulp. Go ahead and create a folder, and within a subfolder with the name tasks. After installing the first module, the structure of our project will look like this:

├── app
│   ├── _assets
│   ├── _data
│   ├── _drafts
│   ├── _includes
│   ├── _layouts
│   ├── _plugins
│   ├── _posts
│   └── index.html
├── gulp
│   └── tasks
├── gulpfile.js
├── node_modules
│   └── require-dir
└── package.json


This tutorial uses Jekyll to build the HTML of the website. Creating a new Jekyll website is fast and easy:

$ gem install jekyll
$ jekyll new app
$ cd app
$ jekyll serve

I don’t install Jekyll globally, but with Bundler. This way, all my Gems will be installed with my project and I don’t have to be concerned about the correct version.

I install Bundler globally:

$ gem install bundler

Now I create an empty file in my projects folder with the name Gemfile and add these lines:

source ""

gem 'jekyll', '~> 2.5.2'
gem 'sass', '>= 3.3'

Now I install the Gems by typing:

$ bundle install

If you installed Jekyll with Bundler, run inside your project directory:

$ bundle exec jekyll new app

Did you install it globally? Then drop the bundle exec from the command.


This concludes the 1st part of my series Introduction to Gulp.js. We learned what Gulp.js is used for and created the basic folder structure for the project.