Just Sharing My Gulpfile

Programming - Mar 31, 2024

Seemingly out of the blue, the Gulp processing I had set up for this site started to have a race condition. I’d run my watch command, change some CSS, and the processing would sometimes leave behind some extra files that were meant to be cleaned up during the processing. Like the cleanup tasks happened before the files landed in the file system (or something… I never really got to the bottom of it).

Nevermind about the specifics of that bug. I figured I’d go about solving it by upgrading things to use Gulp 4.x instead of 3.x, and running things in the built-in gulp.series command, which I thought would help (it did).

Getting Gulp 4.x going was a heck of a journey for me, involving me giving up for a year, then reigniting the struggle and ultimately getting it fixed. My trouble was that Gulp 4 requires a CLI version of 2.x while Gulp 3, for whatever reason, used a 3.x version. Essentially I needed to downgrade versions, but after trying a billion things to do that, nothing seemed to work, like there was a ghost version of CLI 3.x on my machine.

I’m sure savvier command-line folks could have sussed this out faster than me, but it turns out running command -v gulp will reveal the file path of where Gulp is installed which revealed /usr/local/share/npm/bin/gulp for me, and deleting it manually from there before re-installing the lastest version worked in getting me back down to 2.x.

Now that I could use Gulp 4.x, I re-wrote my gulpfile.js into smaller functions, each fairly isolated in responsibility. Much of this is pretty unique to my setup on this site, so it’s not meant to be some boilerplate for generic usage. I’m just publishing because it certainly would have been helpful for me to reference as I was creating it.

Things my particular Gulpfile does

  • Runs a web server (Browsersync) for style injection and auto-refreshing
  • Runs a file watcher (native Gulp feature) for running the right tasks on the right files and doing the above things
  • CSS processing
    • Sass > Autoprefixer > Minify
    • Break stylesheet cache from the templates (e.g. <link href="style.css?BREAK_CACHE">
    • Put style.css in the right place for a WordPress theme and clean up files only needed during processing
  • JavaScript processing
    • Babel > Concatenate > Minify
    • Break browser cache for the <script>s
    • Clean up unused files created in processing
  • SVG processing
    • Make an SVG sprite (a block of <symbol>s
    • Name it as a sprite.php file (so it can be PHP-included in a template) and put it somewhere specific
  • PHP processing
    • Update the Ajax call in the JavaScript to cache-bust when the ads change

Code dump!

const gulp = require("gulp"),
  browserSync = require("browser-sync").create(),
  sass = require("gulp-sass"),
  postcss = require("gulp-postcss"),
  autoprefixer = require("autoprefixer"),
  cssnano = require("cssnano"),
  del = require("del"),
  babel = require("gulp-babel"),
  minify = require("gulp-minify"),
  concat = require("gulp-concat"),
  rename = require("gulp-rename"),
  replace = require("gulp-replace"),
  svgSymbols = require("gulp-svg-symbols"),
  svgmin = require("gulp-svgmin");

const paths = {
  styles: {
    src: ["./scss/*.scss", "./art-direction/*.scss"],
    dest: "./css/"
  scripts: {
    src: ["./js/*.js", "./js/libs/*.js", "!./js/min/*.js"],
    dest: "./js/min"
  svg: {
    src: "./icons/*.svg"
  php: {
    src: ["./*.php", "./ads/*.php", "./art-direction/*.php", "./parts/**/*.php"]
  ads: {
    src: "./ads/*.php"

/* STYLES */
function doStyles(done) {
  return gulp.series(style, moveMainStyle, deleteOldMainStyle, done => {
    cacheBust("./header.php", "./");

function style() {
  return gulp
    .on("error", sass.logError)
    .pipe(postcss([autoprefixer(), cssnano()]))

function moveMainStyle() {
  return gulp.src("./css/style.css").pipe(gulp.dest("./"));

function deleteOldMainStyle() {
  return del("./css/style.css");

function doScripts(done) {
  return gulp.series(
    done => {
      cacheBust("./parts/footer-scripts.php", "./parts/");

function preprocessJs() {
  return gulp
        presets: ["@babel/env"],
        plugins: ["@babel/plugin-proposal-class-properties"]

function concatJs() {
  return gulp

function minifyJs() {
  return gulp
    .src(["./js/babel/*.js", "./js/concat/*.js"])
        ext: {
          src: ".js",
          min: ".min.js"

function deleteArtifactJs() {
  return del([

/* SVG */
function doSvg() {
  return gulp
        templates: ["default-svg"],
        svgAttrs: {
          width: 0,
          height: 0,
          display: "none"
/* END SVG */

function cacheBust(src, dest) {
  var cbString = new Date().getTime();
  return gulp
      replace(/cache_bust=\d+/g, function() {
        return "cache_bust=" + cbString;

function reload(done) {

function watch() {
    proxy: "csstricks.local"
  gulp.watch(paths.styles.src, doStyles);
  gulp.watch(paths.scripts.src, doScripts);
  gulp.watch(paths.svg.src, doSvg);
  gulp.watch(paths.php.src, reload);
  gulp.watch(paths.ads.src, done => {
    cacheBust("./js/global.js", "./js/");

gulp.task("default", watch);

Problems / Questions

  • The worst part is that it doesn’t break cache very intelligently. When CSS changes, it breaks the cache on all stylesheets, not just the relevant ones.
  • I’d probably just inline SVG icons with PHP include()s in the future rather than deal with spriting.
  • The SVG processor breaks if the original SVGs have width and height attributes, which seems wrong.
  • Would gulp-changed be a speed boost? As in, only looking at files that have changed instead of all files? Or is it not necessary anymore?
  • Should I be restarting gulp on gulpfile.js changes?
  • Sure would be nice if all the libs I used were ES6-compatible so I could import stuff rather than having to manually concatenate.

Always so much more that can be done. Ideally, I’d just open-source this whole site, I just haven’t gotten there yet.

Previous Next
We respect the property rights of others, and are always careful not to infringe on their rights, so authors and publishing houses have the right to demand that an article or book download link be removed from the site. If you find an article or book of yours and do not agree to the posting of a download link, or you have a suggestion or complaint, write to us through the Contact Us .
Read More