Learn how to solve this exception when using gulp v3 in Node.js 12.

How to solve gulp exception: Reference Error primordials is not defined error

While working on a project that used gulp on my environment, i noticed that the same project that was working pretty well on the environment of other pals at the office, wasn't working on mine. It was throwing the mentioned exception, Reference error: primordials is not defined error.

It seems that gulp v3 has a trouble when running on a Node.js 12 environment, because one of the dependencies, namely graceful-fs (a drop-in replacement for the fs module, making various improvements), isn't compatible with this version of Node. So, the options to solve the issue were just clear:

  1. Either you upgrade to gulp v4 (modifying your source code, spending a lot of time).
  2. Downgrade specifically the version of graceful-fs in your project.

As we can't just simply rewrite the code as it would not be monetarily profitable for us, the fix was to simply force our project to install the specific version 4.2.2 of graceful-fs. That's what you are going to learn how to do in this article.

1. Delete node_modules

As first step, you will need to remove all the dependencies that you have already installed, because if you try to run npm install, the same dependencies will be kept with the same version, but our solution forces to downgrade graceful-fs. So, simply delete the node_modules directory.

2. Create npm-shrinkwrap.json

After removing the dependencies directory, proceed to create the following file namely npm-shrinkwrap.json file with the following content in the same directory of your project (where package.json is located):

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

You can find a detailed description about this file in the official documentation of NPM here.

3. Install dependencies

After creating the file of the step #2, proceed to install once again the dependencies of your project with npm:

npm install

This will start the installation of the dependencies and npm will warn you about the lockfileversion of the shrinkwrap file:

Gulp Install Node.js Primordials

This will modify as well the previously created npm-shrinkwrap.json file with a lot of content like this:

{
    "name": "yourproject_name",
    "version": "x.x.x",
    "lockfileVersion": 1,
    "requires": true,
    "dependencies": {
        
        // .. //

        "@gulp-sourcemaps/identity-map": {
            "version": "1.0.2",
            "resolved": "https://registry.npmjs.org/@gulp-sourcemaps/identity-map/-/identity-map-1.0.2.tgz",
            "integrity": "sha512-ciiioYMLdo16ShmfHBXJBOFm3xPC4AuwO4xeRpFeHz7WK9PYsWCmigagG2XyzZpubK4a3qNKoUBDhbzHfa50LQ==",
            "dev": true,
            "requires": {
                "acorn": "^5.0.3",
                "css": "^2.2.1",
                "normalize-path": "^2.1.1",
                "source-map": "^0.6.0",
                "through2": "^2.0.3"
            }
        }

        // .. //
    }
}

You can ignore this for the moment. After installing the dependencies, everything should work as expected and the build should succeed as usual:

gulp build --production

Happy coding ❤️!


Senior Software Engineer at Software Medico. Interested in programming since he was 14 years old, Carlos is a self-taught programmer and founder and author of most of the articles at Our Code World.

Sponsors