Motivation ("The Why")

Everybody has seen those warnings from an npm install command where it didn't install an optional dependency, probably because the dependency in question was OS-specific to an OS the installer wasn't running on. A common issue is a warning that fsevents wasn't installed on an OS that wasn't OSX. Furthermore, there are hundreds of packages that are Windows-specific.

Right now, these print as console warnings during the installation process. This shouldn't be a warning, because npm is behaving the way it's supposed to and the correct packages are being installed.

Packages should be allowed to specify that a particular dependency is only used on certain platforms and not others.

Furthermore, the current system can obscure problems. if fsevents is required on OSX in a package and not elsewhere, and it fails to install due to something going wrong on an OSX client, the OSX user and logs will still see that it was just an optional dependency failing to install, even though it was really a mandatory dependency on that platform.

Right now, package.json has devDependencies, dependencies, peerDependencies, bundledDependencies, and optionalDependencies as dependency types; and packages can specify the intended architectures and operating systems of the packages themselves. To fix this problem of warnings that aren't warning about something wrong, the dependency set should be extended to include "platformDependencies".

Example

Right now, chokidar specifies fsevents as an optional depdendency. This means that whenever chokidar is installed on something other than OSX, there is a warning printed. Allowing platform-specific dependencies would solve this issue.

As god-king-emperor StackOverflow has shown, this is a problem in practice: https://stackoverflow.com/questions/38021422/nodejs-npm-install-platform-specific-packages

How

Current Behaviour

Currently, platform-specific dependencies are just treated as optionalDependencies, as shown here: https://github.com/paulmillr/chokidar/blob/e1c37c6207b0b9b970f6479a9a7d238bd3b4de92/package.json

"optionalDependencies": {
    "fsevents": "~2.1.2"
  },

Desired Behaviour

There are several ways this could be done. I think the least awful way to do this is the following:

...
 "platformDependencies": [
    {
      "os": ["darwin"],
      //"arch": [],
      "dependencySet": ["fsevents"]
    },
    {
      "os": ["win32"],
      //"arch": [],
      "dependencySet": ["win32-api", "windows-iana"]
    },
    {
      "os": ["darwin","linux","openbsd",...],
      "arch": ["x32","x64"],
      "dependencySet": ["posix"]
    },
    {
      "os": ["darwin","linux","openbsd",...],
      "arch": ["!x32","!x64"],
      "dependencySet": ["posix"]
    },
  ],
...

There would be a set of objects where a set of OSes and architectures can be specified along with the actual packages. At least 1 of the 2 of os and arch would be required but both being usable, each consisting of at least 1 target. As can be done in the current os and cpu values, the not! syntax can be used on platforms where not required.

References

• n/a

Note: Currently, npm allows packages to specify that they're specific to an OS or architecture. This is a good feature that should be retained. This RFC is not meant to replace this feature but be used alongside it. optionalDependencies is also not being proposed for deprecation because it has use-cases beyond this poorly-fitting one.