🐞 Battling With Gulp and Node

Table of Contents

😨 Problem #

When I was building a website using gulp@^3.9.0 to compile sass on the build server with Node.js v12 installed, it failed.

Here are (part of) the errors shown in the console:

error	26-Jun-2020 08:35:02	gyp ERR! node -v v12.18.0
error	26-Jun-2020 08:35:02	gyp ERR! node-gyp -v v3.8.0
error	26-Jun-2020 08:35:02	gyp ERR! not ok 
error	26-Jun-2020 08:35:02	Build failed with error code: 1
error	26-Jun-2020 08:35:05	
error	26-Jun-2020 08:35:05	npm ERR! code ELIFECYCLE
error	26-Jun-2020 08:35:05	npm ERR! errno 1
error	26-Jun-2020 08:35:05	npm ERR! node-sass@4.9.3 postinstall: `node scripts/build.js`
error	26-Jun-2020 08:35:05	npm ERR! Exit status 1
error	26-Jun-2020 08:35:05	npm ERR! 
error	26-Jun-2020 08:35:05	npm ERR! Failed at the node-sass@4.9.3 postinstall script.
error	26-Jun-2020 08:35:05	npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

(OK I know that’s not your fault, npm.) Here is my package.json:

{
  "devDependencies": {
    "gulp": "^3.9.0",
    "gulp-concat": "^2.6.0",
    "gulp-minify-css": "^1.2.4",
    "gulp-rename": "^1.2.2",
    "gulp-sass": "^4.0.2",
    "gulp-sourcemaps": "*"
  }
}

😐 `node-sass` #

I noticed that should be something wrong with node-sass, which being used in gulp-sass. I met this issues before and from my experience, node-sass will try to download the corresponding prebuilt binary base on your OS or build it locally using python, MSBuild, etc… (That’s why you will met lots of questions in Stack Overflow asking python2 not found when installing node-sass , what’s wrong with my node-sass or I got a panic attack when dealing with node-sass should I consult a developer or a doctor first?).

For this node-sass issue, you can try to run this on Windows:

npm install --global --production windows-build-tools
npm install node-gyp

Or try to delete package-lock.json and node_modules first and do a npm install if you can install all packages successfully on let say Mac OS but failed on Windows.

👆Those tricks saved me most of the time.

I just want to get my css files back and you told me I have to install this and that and download node npm python ms build tools some prebuilt binaries? Are you serious, node-sass? #

😑 ReferenceError: primordials is not defined #

After the node-sass issue was solved, the build server ran the build jobs again and got these errors:

error	26-Jun-2020 08:53:06	fs.js:35
error	26-Jun-2020 08:53:06	} = primordials;
error	26-Jun-2020 08:53:06	    ^
error	26-Jun-2020 08:53:06	
error	26-Jun-2020 08:53:06	ReferenceError: primordials is not defined
error	26-Jun-2020 08:53:06	    at fs.js:35:5
## ( blah blah blah ) ##
error	26-Jun-2020 08:53:06	    at Module._compile (internal/modules/cjs/loader.js:1138:30)
error	26-Jun-2020 08:53:06	    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1158:10)
error	26-Jun-2020 08:53:06	    at Module.load (internal/modules/cjs/loader.js:986:32)
error	26-Jun-2020 08:53:06	    at Function.Module._load (internal/modules/cjs/loader.js:879:14)
error	26-Jun-2020 08:53:06	    at Module.require (internal/modules/cjs/loader.js:1026:19)
error	26-Jun-2020 08:53:06	    at require (internal/modules/cjs/helpers.js:72:18)

This answer from Stack Overflow states that it is due to Node.js v12 does not compatible with Gulp v3 and you need to upgrade Gulp to v4. I know I should do that but I also know that I will meet the Did you forget to signal async completion? issue which also will cause an epic fail of the build unless I re-write the gulp tasks.

I don’t want to change my gulpfile.js and I don’t want to upgrade gulp. Not now. That’s why I started searching for a solution without changing any configurations of the build server as well as the gulp setup in the project.

😀 Solution: adding a `npm-shrinkwrap.json` #

Eventually I found a solution on how to handle this “Gulp VS Node” situation. What we need is create a npm-shrinkwrap.json file under the same directory with package.json.

The content of the json file:

{
  "dependencies": {
    "graceful-fs": {
      "version": "4.2.3"
    }
  }
}

After that I can build the project and finish all the gulp tasks without errors 🎉.

🤔 So, what’s going on? #

From the npm’s official documentation on the npm-shrinkwrap command:

This command repurposes package-lock.json into a publishable npm-shrinkwrap.json or simply creates a new one. The file created and updated by this command will then take precedence over any other existing or future package-lock.json files.

And from the documentation on the npm-shrinkwrap.json:

… Additionally, if both package-lock.json and npm-shrinkwrap.json are present in a package root, package-lock.json will be ignored in favor of this file.

In other words, this file has a higher priority then package-lock.json. However, why this file can solve the build error?

The`fs` module #

Node’s fs module got some changes since v11.15 which cause the graceful-fs@^3.0.0 package does not work anymore. Unfortunately, gulp@3.9.1 depends on graceful-fs@^3.0.0. As a result, running the gulp tasks on Node.js v12 will cause the primordials is not defined error.

The fix #

After we added the npm-shrinkwrap.json, from my understanding it locked down the version of package(s) used by the execution environment to the version stated in that file (and ignore the setup in package-lock.json.In the above case, the npm-shrinkwrap.json tells Node.js 12 use graceful-fs@4.2.3 instead of graceful-fs@^3.0.0. This combination works. Meanwhile, the gulp package will still reference to the package.json and package-lock.json file and use the graceful-fs@^3.0.0 package. This combination also works.

🎯 Conclusion #

I got some build errors when using gulp@^3.9.0 and gulp-sass under Node.js 12. After I delete the package-lock.json and re-run npm install, the sass problem solved. Next, I added a npm-shrinkwrap.json to (temporarily) solve the incompatable issue with old gulp running on new Node.js.