How do we improve the missing binary experience?

[extempl]

This is mostly a copy of the #1764 and npm rebuild node-sass actually helps.

But

the issue here is that I need to search for how-to-fix that error. It should, at least, show message try to run 'npm rebuild node-sass', or better ask user is he wants to do rebuild and rebuild by button click or answer yes in the console.

Currently the issue #1764 is not fixed. It is like "hey, we have workaround here, search by yourself".

P.S. in my case it just started to show the message after node and npm update. So the message "does not yet supported" is wrong in the root.

[extempl]

I'd say that the error message is correct in case it shown something like this "current node-sass package was built for node lower version and can't be run in this version. You need to do rebuild with command npm rebuild node-sass". That's a correct error handler with correct advice how to solve problem.

[xzyfer]

There are a couple different conditions here.

user has an older version of node-sass, and updates to a new (unsupported) version of Node

This is your case.

Error: Node Sass does not yet support your current environment: OS X 64-bit with Unsupported runtime (64)
For more information on which environments are supported please see:
https://github.com/sass/node-sass/releases/tag/v4.8.3

We tell to user that they're now on a version of Node that isn't supported. Their only option is to use a version of Node that is supported. They're given a link to see what version are supported.

user has a new version on node-sass, and updates to a new (supported) version of Node

Error: Missing binding /Users/xzyfer/Projects/Sass/node-sass/vendor/darwin-x64-64/binding.node
Node Sass could not find a binding for your current environment: OS X 64-bit with Node.js 10.x

Found bindings for the following environments:

• OS X 64-bit with Node.js 9.x

This usually happens because your environment has changed since running npm install.
Run npm rebuild node-sass --force to build the binding for your current environment.

Here they are told that they're using different version of Node than when they ran npm install. They can fix their issue by running a command.

Note: the command show is wrong. I will fix this. I should be npm rebuild node-sass

---

In the first case, we can't tell the user to just run npm rebuild node-sass. Doing a rebuild on an unsupported Node version will

• attempt to download a binary that cannot exist, then
• fallback to doing a local compilation

Local compilations suck, are slow, and quite possibly will not work because

• between major version updates the V8 APIs can change, also
• there are a lot of environments Node runs i.e. electron, aix, arm, etc..

The users only option is to use a supported version, or update node-sass itself.

---

Now if you think there is a way to more clearly communicate those issue then we're open to suggestions. It's taken us a long time to get this far, it's not an easy problem.

[extempl]

So, the Node 10 is unsupported (I have scrolled to the very bottom on the releases page) and it have shown to me the first variant. But the rebuild have fixed the issue. Why if it is unsupported? Was it a fallback to doing a local compilation which worked despite of quite possibly will not work between major version updates?

As of the first variant of the message - Unsupported environment with OS X 64-bit for me is like "Oh, your Mac OS does not yet supported". And I like "Wtf, it worked before, environment the same". So by environment or Unsupported runtime (64) (is this about node?) it probably should show more human-readable variant. So, technically I know, that the problem was in that I've updated Node, but in this certain message I do not understand this.
Moreover, the link to releases with list of releases and some barely readable names does not help either. But the list at the very bottom helps.
The thing here is that you know that there is a Supported Environments section at the bottom. But users who seeing this page first time - doesn't. They scroll list a bit, sees list of files, understands that it is release page (I quite familiar with github) and closes the page.

[xzyfer]

Unsupported runtime (64)

Every version of Node has a "module version". This is the 64 we show in error above. This number relates to the Node ABI. When the number changes we need to re-build a new binary for the binary to be compatible with Node.

We maintain a mapping of these version numbers to human readable Node version names. We even call the function getHumanNodeVersion. There here is that we cannot know what that number will be until a new version Node is released.

Local compilations suck, are slow, and quite possibly will not work ...

Sometimes you get lucky and it's fine. Sometimes it wont. It depends on what things changed in that version of Node. If the Node C++ APIs changed in a not backwards compatible way then we need to update our C++ code to be compatible.

This situation is getting better thanks to the new N-API that just went stable in Node 10. So in the future, local compilation will be more reliable between Node versions, but will still be slow and suck!

[extempl]

Unsupported runtime (64)

This number relates to the Node ABI

Got it. So by coincidence, I thought that it is related to 64-bit and does not really matters and the whole string is about OS I am running.

For more information on which environments are supported please see:

I'd change the link to section (not sure, is it possible in release details) here, or, at least, change message to For more information look for the 'Supported Environments' section on the page:.

Sometimes you get lucky and it's fine.

So you can't say here, will it be lucky for everyone who now will update node version to 10, or not, correct? Or if in 10th version nothing were changed on C++ APIs - rebuild will work for everyone, despite 10 version is unsupported? I kinda lost here.
Probably you can't say, as if you could, than it probably will be supported.

[xzyfer]

You've some raise good points. About the visibility of the supported environments.

The recent GitHub release page redesign has moved the release assets above the changelog copy. This big list of jibberish links is overwhelming, and doesn't signal there's anything to see below.

It would be good if we could make these more visible, and obvious.

[xzyfer]

I thought that it is related to 64-bit

That also matters. It's listed as either x64 64-bit, or x86 or ia32 for 32-bit.

For more information look for the 'Supported Environments' section on the page

The complication with this is that the supported environments are specific to particular releases. Alternative could be a better structure changelog instead of GitHub releases.

So you can't say here, will it be lucky for everyone who now will update node version to 10, or not, correct?

It means that nothing changed in V8 that broke the C++ APIs we use. Which means anyone who runs a rebuild will be able to successfully compiled the node-sass C++ code locally , if they have the correct compiler too chain to do so. Most Windows and linux users will not be default.

The thing is we can't know if there will be a breaking C++ API change until that version of Node is released.

Probably you can't say, as if you could, than it probably will be supported

When we say unsupported, we mean is for that node-sass + Node version combination

• we don't test it in CI so there might be issues in the C++ code
• we don't have binaries you can just download so npm install and npm rebuild node-sass will fail to download the binary and fallback to trying to compile locally.

[xzyfer]

Note: once we migrate our C++ to the new N-API it's much less likely new versions of Node will break our C++ code.