Gulp is intended to save us time, and it would seem that taking too much time troubleshooting Gulp would reverse its value. Yet, every step you take to troubleshoot Gulp is a step toward posterity; you’ll be better-equipped to troubleshoot future projects. Not to mention, you’ll be able to help your teammates and possibly write a blog-post on the subject.
Missing Module/Plugin
With a Gulp-enabled project, there is ideally a package.json file that will allow you to use `npm install` to install the packages needed for this particular Gulp to run properly. However, your gulpfile.js might reference a module that isn’t referenced in package.json.
You can see in the above screenshot that the gulpfile.js is requiring gulp-plumber, but the package.json doesn’t list it as a dependency. This typically happens when a developer uses the `npm install somefancymodule` command without using the --save-dev modifier. Luckily, all you have to do is correct that by using --save-dev. In this example, the following command would add the gulp-plumber module to the list of dependencies in package.json: `npm install gulp-plumber --save-dev`.
Post NPM-Install Issues
Sometimes (for whatever reason) the `npm install` errors-out or doesn’t install all of the required plugins. This results in having to manually install each module.
If our package.json looks something like this:
Then installing each of the modules would mean running `npm install gulp-autoprefixer` followed by `npm install gulp-imagemin` followed by … you get the picture. You could also use your favorite multi-line editor to isolate the plugin-lines and format to work as a single terminal command-string. That would look something like the following for this package.json:
`npm install gulp-autoprefixer && npm install gulp-imagemin && npm install gulp-sass && npm install gulp-watch`
Other Issues
Occasionally you’ll receive a general NodeJS-based error. These are usually the most difficult to address. They can range from proxy and connection issues to syntax problems to old or unsupported module references.
At the time I was writing this post, a teammate posted “/me curses gulp” into our Slack. She was having a number of issues with her Node installation. Eventually she reinstalled NodeJS, walked through a number of troubleshooting steps, and stepped away for a bit to take a break. Upon returning, she quit and re-opened Terminal, ran the install operations again and everything worked as intended. Turns out the quitting/re-opening Terminal did the trick, as there were changes to her bash profile that hadn’t been recognized yet.
If you’re slamming your head against a wall, take a deep breath, put down that baseball bat and just take a wee little break. Come back with a fresh mind (and some jerky or maybe a string cheese) and give it another go.
Gulp Error Management: Plumber
Pobody is nerfect, which means you’ll likely be screwing up your beautiful Sass with some incorrect syntax or by calling the wrong mixin. By default, Gulp likes to break the piping stream and totally freak out. Then you have to re-run Gulp and try to figure out what went wrong. Each step of the way you’ll be re-running Gulp, which can get tiresome if you’re troubleshooting a bracketing/nesting error.
In comes Plumber - it’s a Gulp plugin that prevents Gulp from breaking it’s stream on-error. This means you don’t have to keep re-running Gulp every time there’s an error, since Gulp no longer quits when it experiences an error. Plumber is really easy to use and is too convenient to pass-up.
