Point users towards prebuildify

README.md

@@ -1,18 +1,36 @@
 # prebuild-install
 
-> A command line tool to easily install prebuilt binaries for multiple version of node/iojs on a specific platform.
+> **A command line tool to easily install prebuilt binaries for multiple versions of Node.js & Electron on a specific platform.**
+> By default it downloads prebuilt binaries from a GitHub release.
 
 [![npm](https://img.shields.io/npm/v/prebuild-install.svg)](https://www.npmjs.com/package/prebuild-install)
 ![Node version](https://img.shields.io/node/v/prebuild-install.svg)
 [![Test](https://github.com/prebuild/prebuild-install/actions/workflows/test.yml/badge.svg)](https://github.com/prebuild/prebuild-install/actions/workflows/test.yml)
 [![david](https://david-dm.org/prebuild/prebuild-install.svg)](https://david-dm.org/prebuild/prebuild-install)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)
 
-`prebuild-install` supports installing prebuilt binaries from GitHub by default.
+## Note
+
+**Instead of [`prebuild`](https://github.com/prebuild/prebuild) paired with [`prebuild-install`](https://github.com/prebuild/prebuild-install), we recommend [`prebuildify`](https://github.com/prebuild/prebuildify) paired with [`node-gyp-build`](https://github.com/prebuild/node-gyp-build).**
+
+With `prebuildify`, all prebuilt binaries are shipped inside the package that is published to npm, which means there's no need for a separate download step like you find in `prebuild`. The irony of this approach is that it is faster to download all prebuilt binaries for every platform when they are bundled than it is to download a single prebuilt binary as an install script.
+
+Upsides:
+
+1. No extra download step, making it more reliable and faster to install.
+2. Supports changing runtime versions locally and using the same install between Node.js and Electron. Reinstalling or rebuilding is not necessary, as all prebuilt binaries are in the npm tarball and the correct one is simply picked on runtime.
+3. The `node-gyp-build` runtime dependency is dependency-free and will remain so out of principle, because introducing dependencies would negate the shorter install time.
+4. Prebuilt binaries work even if npm install scripts are disabled.
+5. The npm package checksum covers prebuilt binaries too.
+
+Downsides:
+
+1. The installed npm package is larger on disk. Using [Node-API](https://nodejs.org/api/n-api.html) alleviates this because Node-API binaries are runtime-agnostic and forward-compatible.
+2. Publishing is mildly more complicated, because `npm publish` must be done after compiling and fetching prebuilt binaries (typically in CI).
 
 ## Usage
 
-Change your package.json install script to:
+Use [`prebuild`](https://github.com/prebuild/prebuild) to create and upload prebuilt binaries. Then change your package.json install script to:
 
 ```json
 {
@@ -22,10 +40,6 @@ Change your package.json install script to:
 }
 ```
 
-### Requirements
-
-You need to provide prebuilds made by [`prebuild`](https://github.com/prebuild/prebuild).
-
 ### Help
 
 ```
@@ -46,9 +60,9 @@ prebuild-install [options]
   --version                     (print prebuild-install version and exit)
 ```
 
-When `prebuild-install` is run via an `npm` script, options
-`--build-from-source`, `--debug`, `--download`, `--target`, `--runtime`, `--arch` and `--platform` may be passed through via
-arguments given to the `npm` command. Alternatively you can set environment variables `npm_config_build_from_source=true`, `npm_config_platform`, `npm_config_arch`, `npm_config_target` and `npm_config_runtime`.
+When `prebuild-install` is run via an `npm` script, options `--build-from-source`, `--debug`, `--download`, `--target`, `--runtime`, `--arch` and `--platform` may be passed through via arguments given to the `npm` command.
+
+Alternatively you can set environment variables `npm_config_build_from_source=true`, `npm_config_platform`, `npm_config_arch`, `npm_config_target` and `npm_config_runtime`.
 
 ### Private Repositories