From cc4712affad2d1900d5510dd5e57ee134e2c4f3e Mon Sep 17 00:00:00 2001 From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com> Date: Thu, 9 Oct 2025 10:29:40 +0200 Subject: [PATCH] docs: clarify postinstall requirements (#48497) postinstall Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com> Co-authored-by: Erick Zhao --- docs/faq.md | 25 +++++++++++++++++-------- docs/tutorial/installation.md | 12 ++++++------ docs/tutorial/tutorial-2-first-app.md | 20 ++++++++++++++++---- 3 files changed, 39 insertions(+), 18 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index b7259d1661b3..34aa74b04ab0 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -12,19 +12,28 @@ network problems. The best resolution is to try switching networks, or wait a bit and try installing again. You can also attempt to download Electron directly from -[electron/electron/releases](https://github.com/electron/electron/releases) +[GitHub Releases](https://github.com/electron/electron/releases) if installing via `npm` is failing. -## When will Electron upgrade to latest Chrome? +If you need to install Electron through a custom mirror or proxy, see +the [Advanced Installation](./tutorial/installation.md) documentation for more details. -The Chrome version of Electron is usually bumped within one or two weeks after -a new stable Chrome version gets released. This estimate is not guaranteed and -depends on the amount of work involved with upgrading. +## How are Electron binaries downloaded? -Only the stable channel of Chrome is used. If an important fix is in beta or dev -channel, we will back-port it. +When you run `npm install electron`, the Electron binary for the corresponding version is downloaded +into your project's `node_modules` folder via npm's `postinstall` lifecycle script. -For more information, please see the [security introduction](tutorial/security.md). +This logic is handled by the [`@electron/get`](https://github.com/electron/get) utility package +under the hood. + +## When will Electron upgrade to latest Chromium? + +Every new major version of Electron releases with a Chromium major version upgrade. By releasing every +8 weeks, Electron is able to pull in every other major Chromium release on the very same day that it +releases upstream. Security fixes will be backported to stable release channels ahead of time. + +See the [Electron Releases](./tutorial/electron-timelines.md) documentation for more details or +[releases.electronjs.org](https://releases.electronjs.org) to see our Release Status dashboard. ## When will Electron upgrade to latest Node.js? diff --git a/docs/tutorial/installation.md b/docs/tutorial/installation.md index c96de676358d..821611a92250 100644 --- a/docs/tutorial/installation.md +++ b/docs/tutorial/installation.md @@ -26,12 +26,12 @@ any dependencies in your app will not be installed. ## Customization -If you want to change the architecture that is downloaded (e.g., `ia32` on an -`x64` machine), you can use the `--arch` flag with npm install or set the +If you want to change the architecture that is downloaded (e.g., `x64` on an +`arm64` machine), you can use the `--arch` flag with npm install or set the `npm_config_arch` environment variable: ```shell -npm install --arch=ia32 electron +npm install --arch=x64 electron ``` In addition to changing the architecture, you can also specify the platform @@ -60,7 +60,7 @@ where `$VERSION` is the exact version of Electron). If you are unable to access GitHub or you need to provide a custom build, you can do so by either providing a mirror or an existing cache directory. -#### Mirror +### Mirror You can use environment variables to override the base URL, the path at which to look for Electron binaries, and the binary filename. The URL used by `@electron/get` @@ -95,7 +95,7 @@ Electron release you may have to set `electron_use_remote_checksums=1` directly, or configure it in a `.npmrc` file, to force Electron to use the remote `SHASUMS256.txt` file to verify the checksum instead of the embedded checksums. -#### Cache +### Cache Alternatively, you can override the local cache. `@electron/get` will cache downloaded binaries in a local directory to not stress your network. You can use @@ -120,7 +120,7 @@ The cache contains the version's official zip file as well as a checksum, and is │ └── electron-v15.3.1-darwin-x64.zip ``` -## Skip binary download +## Postinstall script Under the hood, Electron's JavaScript API binds to a binary that contains its implementations. Because this binary is crucial to the function of any Electron app, diff --git a/docs/tutorial/tutorial-2-first-app.md b/docs/tutorial/tutorial-2-first-app.md index 465c98c0bf26..b4ed50d4b7e0 100644 --- a/docs/tutorial/tutorial-2-first-app.md +++ b/docs/tutorial/tutorial-2-first-app.md @@ -58,11 +58,12 @@ There are a few rules to follow for the purposes of this tutorial: Then, install Electron into your app's **devDependencies**, which is the list of external development-only package dependencies not required in production. -:::info Why is Electron a devDependency? +:::info Why is Electron a dev dependency? -This may seem counter-intuitive since your production code is running Electron APIs. -However, packaged apps will come bundled with the Electron binary, eliminating the need to specify -it as a production dependency. +This may seem counter-intuitive since your production code is running Electron APIs. Under the hood, +Electron's JavaScript API binds to a binary that contains its implementations. The packaging step for +Electron handles the bundling of this binary, eliminating the need to specify it as a production +dependency. ::: @@ -70,6 +71,17 @@ it as a production dependency. npm install electron --save-dev ``` +:::warning + +In order to correctly install Electron, you need to ensure that its `postinstall` lifecycle +script is able to run. This means avoiding the `--ignore-scripts` flag on npm and allowlisting +`electron` to run build scripts on other package managers. + +This is likely to change in a future version of Electron. See +[electron/rfcs#22](https://github.com/electron/rfcs/pull/22) for more details. + +::: + Your package.json file should look something like this after initializing your package and installing Electron. You should also now have a `node_modules` folder containing the Electron executable, as well as a `package-lock.json` lockfile that specifies