Resolving node‑sass Compatibility Issues in Frontend Projects

Preface

Many frontend developers encounter problems with node-sass such as installation failures, compilation errors, or runtime crashes. The root cause is usually a mismatch between the node-sass version and the Node.js version it depends on.

Project Dependency Information

The project's package.json contains the following relevant entries:

"dependencies"
: {
  "node-sass": "^4.12.0",
  "sass-loader": "^7.0.1",
  ...
},
"devDependencies": {
  "node-sass": "^4.12.0",
  "sass-loader": "^7.0.1",
  ...
}

Node and node‑sass Version Mapping

NodeJS

node‑sass version

Node Module

Node 20

9.0+

115

Node 19

8.0+

111

Node 18

8.0+

108

Node 17

7.0+, <8.0

102

Node 16

6.0+

93

Node 15

5.0+, <7.0

88

Node 14

4.14+, <9.0

83

Node 13

4.13+, <5.0

79

Node 12

4.12+, <8.0

72

Node 11

4.10+, <5.0

67

Node 10

4.9+, <6.0

64

Node 8

4.5.3+, <5.0

57

Node <8

<5.0

<57

Common Matching Versions of node‑sass and sass‑loader

node‑sass

sass‑loader

4.3.0

4.1.1

4.7.2

7.0.3

4.7.2

7.3.1

4.12.0

7.0.1

4.14.1

8.0.0

4.14.1

7.3.1

6.0.1

10.0.1

Solution 1 – Switch Node Version

According to the version table, install the Node version that matches the required node‑sass / sass‑loader versions. The author uses nvm to manage Node versions.

In the example project the node‑sass version is 4.12.0 , which maps to Node 12. Install and switch to Node 12:

nvm install 12.22.12
nvm use 12.22.12
nvm alias default 12.22.12

cnpm Install Error

After switching Node, running cnpm i may still fail with Error: Cannot find module 'fs/promises' because the Node version is too low for the current cnpm version.

npm Install Error

Running npm i can produce ValueError: invalid mode: 'rU' while trying to load binding.gyp . The author retries cnpm i in a new terminal where Node is 16.x, which succeeds.

Solution 2 – Modify Dependency Versions

Check the Node version with node -v , then adjust node‑sass and sass‑loader in package.json to versions that match the current Node. This approach is not recommended for collaborative projects.

Install matching versions directly:

npm install node-sass@
VERSION
sass-loader@
VERSION
--save-dev
cnpm install sass-loader@
VERSION
node-sass@
VERSION
--save-dev

Solution 3 – Replace node‑sass with sass

Delete node‑sass and install sass (e.g., "sass": "^1.60.0" ). This works if the project does not rely on node‑sass specific features, but may require code adjustments such as removing semicolons or changing lang="sass" to lang="scss" .

Install sass:

cnpm i [email protected] -D

Resulting dependencies:

"sass"
: "^1.60.0",
"sass-loader"
: "^7.0.1"

Packaging Error

Running npm run build fails because the terminal is still using a Node version other than the required 12. Switch to Node 12 first, then rebuild.

Other Notes

If the npm registry does not contain required files, switch back to the official registry or use a proxy.

Some native dependencies need a C++ build environment (e.g., Visual Studio 2022) and Python.

Reference Article

See the article about fixing invalid mode: ‘rU’ while trying to load binding.gyp caused by mismatched node‑gyp and Python versions.

Summary

The article records a step‑by‑step process for stabilizing projects that depend on node‑sass . The key is to ensure the Node.js version matches the node‑sass version, and if that fails, either adjust dependency versions or replace node‑sass with sass . Proper environment setup (Node version, C++/Python tools) and careful handling of package managers (npm, cnpm, nvm) are essential for a successful build.