|
|
@@ -1,8 +1,9 @@
|
|
|
# Using Native Node Modules
|
|
|
|
|
|
-Native Node modules are supported by Electron, but since Electron is very
|
|
|
-likely to use a different V8 version from the Node binary installed on your
|
|
|
-system, the modules you use will need to be recompiled for Electron. Otherwise,
|
|
|
+Native Node.js modules are supported by Electron, but since Electron has a different
|
|
|
+[application binary interface (ABI)][abi] from a given Node.js binary (due to
|
|
|
+differences such as using Chromium's BoringSSL instead of OpenSSL), the native
|
|
|
+modules you use will need to be recompiled for Electron. Otherwise,
|
|
|
you will get the following class of error when you try to run your app:
|
|
|
|
|
|
```sh
|
|
|
@@ -23,9 +24,11 @@ You can install modules like other Node projects, and then rebuild the modules
|
|
|
for Electron with the [`electron-rebuild`][electron-rebuild] package. This
|
|
|
module can automatically determine the version of Electron and handle the
|
|
|
manual steps of downloading headers and rebuilding native modules for your app.
|
|
|
+If you are using [Electron Forge][electron-forge], this tool is used automatically
|
|
|
+in both development mode and when making distributables.
|
|
|
|
|
|
-For example, to install `electron-rebuild` and then rebuild modules with it
|
|
|
-via the command line:
|
|
|
+For example, to install the standalone `electron-rebuild` tool and then rebuild
|
|
|
+modules with it via the command line:
|
|
|
|
|
|
```sh
|
|
|
npm install --save-dev electron-rebuild
|
|
|
@@ -33,12 +36,12 @@ npm install --save-dev electron-rebuild
|
|
|
# Every time you run "npm install", run this:
|
|
|
./node_modules/.bin/electron-rebuild
|
|
|
|
|
|
-# On Windows if you have trouble, try:
|
|
|
+# If you have trouble on Windows, try:
|
|
|
.\node_modules\.bin\electron-rebuild.cmd
|
|
|
```
|
|
|
|
|
|
-For more information on usage and integration with other tools, consult the
|
|
|
-project's README.
|
|
|
+For more information on usage and integration with other tools such as [Electron
|
|
|
+Packager][electron-packager], consult the project's README.
|
|
|
|
|
|
### Using `npm`
|
|
|
|
|
|
@@ -147,23 +150,25 @@ for an example delay-load hook if you're implementing your own.
|
|
|
native Node modules with prebuilt binaries for multiple versions of Node
|
|
|
and Electron.
|
|
|
|
|
|
-If modules provide binaries for the usage in Electron, make sure to omit
|
|
|
-`--build-from-source` and the `npm_config_build_from_source` environment
|
|
|
-variable in order to take full advantage of the prebuilt binaries.
|
|
|
+If the `prebuild`-powered module provide binaries for the usage in Electron,
|
|
|
+make sure to omit `--build-from-source` and the `npm_config_build_from_source`
|
|
|
+environment variable in order to take full advantage of the prebuilt binaries.
|
|
|
|
|
|
## Modules that rely on `node-pre-gyp`
|
|
|
|
|
|
The [`node-pre-gyp` tool][node-pre-gyp] provides a way to deploy native Node
|
|
|
modules with prebuilt binaries, and many popular modules are using it.
|
|
|
|
|
|
-Usually those modules work fine under Electron, but sometimes when Electron uses
|
|
|
-a newer version of V8 than Node and/or there are ABI changes, bad things may
|
|
|
-happen. So in general, it is recommended to always build native modules from
|
|
|
-source code. `electron-rebuild` handles this for you automatically.
|
|
|
+Sometimes those modules work fine under Electron, but when there are no
|
|
|
+Electron-specific binaries available, you'll need to build from source.
|
|
|
+Because of this, it is recommended to use `electron-rebuild` for these modules.
|
|
|
|
|
|
-If you are following the `npm` way of installing modules, then this is done
|
|
|
-by default, if not, you have to pass `--build-from-source` to `npm`, or set the
|
|
|
-`npm_config_build_from_source` environment variable.
|
|
|
+If you are following the `npm` way of installing modules, you'll need to pass
|
|
|
+`--build-from-source` to `npm`, or set the `npm_config_build_from_source`
|
|
|
+environment variable.
|
|
|
|
|
|
+[abi]: https://en.wikipedia.org/wiki/Application_binary_interface
|
|
|
[electron-rebuild]: https://github.com/electron/electron-rebuild
|
|
|
+[electron-forge]: https://electronforge.io/
|
|
|
+[electron-packager]: https://github.com/electron/electron-packager
|
|
|
[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp
|
Mark Lee