diff --git a/packages/grpc-native-core/README.md b/packages/grpc-native-core/README.md index 200b2fca..aa4ac2ec 100644 --- a/packages/grpc-native-core/README.md +++ b/packages/grpc-native-core/README.md @@ -14,6 +14,26 @@ Install the gRPC NPM package npm install grpc ``` +## ABOUT ELECTRON + +The official electron documentation recommends to [build all of your native packages from source](https://electronjs.org/docs/tutorial/using-native-node-modules#modules-that-rely-on-node-pre-gyp). While the reasons behind this are technically good - many native extensions won't be packaged to work properly with electron - the gRPC source code is fairly difficult to build from source due to its complex nature, and we're also providing working electron pre-built binaries. Therefore, we recommend that you do not follow this model for using gRPC with electron. Also, for the same reason, `electron-rebuild` will always build from source. We advise you to not use this tool if you are depending on gRPC, and use the following instructions instead. + +The best to get gRPC to work with electron is to do this, possibly in your postinstall script in your `package.json` file: + +``` +npm rebuild --target=2.0.0 --runtime=electron --dist-url=https://atom.io/download/electron +``` + +Note that the `2.0.0` above is the electron runtime version number. You will need to update this every time you go on a different version of the runtime. + +If you have more native dependencies than gRPC, and they work better when built from source, you can explicitely specify which extension to build the following way: + +``` +npm rebuild --build-from-source=sqlite3 --target=2.0.0 --runtime=electron --dist-url=https://atom.io/download/electron +``` + +This way, if you depend on both `grpc` and `sqlite3`, only the `sqlite3` package will be rebuilt from source, leaving the `grpc` package to use its precompiled binaries. + ## BUILD FROM SOURCE 1. Clone [the grpc Git Repository](https://github.com/grpc/grpc). 2. Run `npm install --build-from-source` from the repository root.