How to Install Gulp.js on Windows

A Mr Stewart Doxey requested a tutorial on installing Gulp.js on Windows.

Step 1 – Install Node.js

Head on over to http://nodejs.org and click install – this should use magic to figure out what OS and version.

Step 2 – Install Gulp.js

gulp-2x Open command prompt – (run cmd) then type ‘npm’ – if there is no  error you’ve installed Node.js correctly yay! Otherwise make sure you close and reopen command prompt if it was open during install. Or try rebooting – reinstalling, the usual.

Now type ‘npm install -g gulp’ this will install Gulp.js globally on your system. It will enable you to run the ‘gulp’ command in your command prompt.

You will now need to go ‘npm install gulp’ to locally install Gulp to your project root directory. You’ll have to do this for each new project where you wish to use Gulp.

Type ‘gulp’ it should say no gulpfile found this means its installed correctly.

Step 3- Setup your project

You need two files in your project, package.json and gulpfile.js. If you doing a Node.js project already you know about package.json, otherwise read on.

What is package.json? It’s a  file that tells npm what dependencies your code needs. It allows npm to install automatically all dependencies.

npm works on a system of not including your dependencies in your version control. So add node_modules to your .gitignore file. Simply add ‘node_modules’ to the bottom.

Grab your package.json and gulpfile.js files, ready made for your convenience. A special mention has to go to Myke for his SASS error display code in the gulpfile.js. – More on that later.

Plop these two files in the root of your project. Open your command prompt cd your way to there. Now run ‘npm link’. This will scurry away installing all your needed dependencies and using magical symlinks to link them into your project.

Install Complete

Step 4 – Configure your project

Open up gulpfile.js on Line 14, you configure your SASS directories you wish to watch. You may only want one, or ten, its all in JavaScript go mad.

logo-235e394c

Configure SASS

You must already have ruby-sass installed on your computer! if you don’t have this, you’ll need to google how to install ruby sass on Windows. I may make a tutorial on how to do that another time.

The directory to watch – in this example we are watching all files AND sub directories in the _scss/Site/ directory.

watch: '_scss/Site/**/*.scss',

The master sass file, we compile from this file.

sass: '_scss/Site/site.scss',

Output folder

output: './www/app/View/Themed/Site/webroot/css',

Output file name

name: 'site.css',

JavaScript-logo

Configure JS concatenation

We’re off to line 28 (in the original file, duh) to change the JS settings. Again you can watch multiple directories and output to multiple places.

Watch JavaScript files for changes

watch: '_assets/admin/*.js',

Output folder

output: './www/app/View/Themed/Admin/webroot/js/',

Output filename

name: 'admin.js',

Output filename minified

nameMin: 'admin.min.js'

This creates two version of your JS, a minified and non-minified, good for debugging.

Why Sass? Because its better than CSS
Why JS concatenation? Because fewer requests are better, and minifiying is the way to go.

All set!

Step 5 – Run it!

You should be able to run ‘gulp’. It should then go off and start watching all your files.

All new files you create are automatically watched! – This is why we are using gulp-watch instead of the built in watch script. No need to restart gulp.

SASS errors will be displayed in your  CSS, with a background colour and the error message. – Just refresh the page and you’ll see the error quickly and easily.

This script includes live reload so download the live reload extension to Chrome and once Gulp is running click the icon, it’ll change  a tiny amount, so you’ll end up clicking it a lot and turning it on and off. But when its actually synced your SASS changes will auto load into your browser as you press save. Pretty cool.

You may notice that the example gulpfile.js file has the directory paths for CakePHP setup. If you’re using that, lucky you!

Why Ruby Sass? Why not libsass? Alas, libsass cannot compile bootstrap or inuit. Once it can I’ll be happy to remove the ruby dependency.

Updated 02/04/2014 Fixed some errors in package.json  – Thanks to Sam

21 Comments

  1. says:

    April 16, 2014 at 6:21 pm

    I followed this tutorial and now my life is complete!

    “How can you pay back a man who teaches you how to write your own name, Captain?”
    Major Richard Sharpe – Spain, 1809

  2. Leonhard says:

    April 3, 2015 at 8:20 pm

    Thanks for this tutorial.
    Unfortunately if I do exactly as described, I get an error when I try to run the “gulp” command.

    ‘watch* errored after XXms
    Error in plugin ‘gulp-watch’
    Message:
    glob should be String or Array, not object

    Is it possible that the given gulpfile.js is out of date?

  3. Nicholas says:

    May 31, 2015 at 11:30 pm

    Hi, Ollie, great tutorial! I might be in over my head here, I followed this instructions and adapted the configuration options to my set up as follows
    var sassFiles = [{watch: '/postomege/sass/**/*.scss',sass: '/postomega/sass/styles.scss',output: 'postomega/css',name: 'styles.css',},

    When I run ‘gulp’ from the command line at the root of my project folder, it opens the gulp file in my text editor. I’m not sure if gulp if is working or not. I’m also experiencing successive xampp crashes, which I’m not sure if they are related? Any advice on where I might I have stumbled?

    • Ollie McFarlane says:

      August 8, 2015 at 12:02 pm

      This sounds like your paths are either setup wrong – or you have a file named gulp with no extension in your project root, and windows is getting confused?

  4. fireton says:

    July 31, 2015 at 3:18 am

    Tried to install gulp but when running it keep getting message:

    [06:16:32] Local gulp not found in D:\Temp\snowman
    [06:16:32] Try running: npm install gulp

    even though I did installed gulp globally with npm install -g gulp

    Any ideas?

    • Ollie McFarlane says:

      August 8, 2015 at 11:59 am

      Sorry, you will need to install it globally and locally. I’ll update the tutorial to make this clear. You’ll have to run npm install gulp in the project folder you’d like to run gulp from

  5. says:

    August 12, 2015 at 12:10 pm

    Thank you! Good article. I just want to inform that, we need to run “npm install gulp” and “npm install gulp -g” command in Administrative privilege.

  6. Ivan Gasparetto says:

    September 19, 2015 at 10:03 am

    Thanks for the tutorial.

    I have the following configuration:


    var sassFiles = [
    {
    watch: 'vendors/bootstrap/bootstrap-3.3.5/less/*.scss',
    sass: 'vendors/bootstrap/bootstrap-3.3.5/less/bootstrap.scss',
    output: './css/bootstrap/',
    name: 'bootstrap.css',
    }
    ,
    {
    watch: 'css/sass/*.scss',
    sass: 'css/sass/app.scss',
    output: './css/',
    name: 'app.min.css',
    }
    ];

    When I run `gulp` the files are not generated. How do I debug it? What can go wrong? How do I know if gulp found the scss files in the specified folder?

    Thanks a lot

  7. developer says:

    December 4, 2015 at 1:18 am

    Gulp is pretty much garbage imo. If you can get it to work, the idea behind it is fantastic. Installing it is a breeze, but getting it to work on windows is a joke. If something like this worked well, then it would be fantastic. Unfortunately, gulp does not.

    • dev0 says:

      January 21, 2016 at 1:37 pm

      Problem is not Gulp but Windows. Windows is a kindergarten OS, not meant for using developer tools. I’m through this process on Windows 7 and OSX. Guess which one is fun and which one is a pure pain in the ass. Hint: Not made by Apple …

  8. says:

    September 22, 2016 at 10:36 am

    Great,man, but,i have a little doubt. I watch some videos and the package.json creates automathically when you write npm init, but in my project no create thar file.
    Must i create that files and copy/paste all dependencies and other plugins inside..or adding somehow?. Sorry my ignorance…Before follow your tutorial, i want to know if i must create the files or from my terminal auto create…
    p.d–Sorry my english, and cheers from Spain

Leave a Reply

Your email address will not be published. Required fields are marked *