github/electron
1
1
Fork 0
mirror of https://github.com/electron/electron.git synced 2026-04-10 03:01:51 -04:00
Code Issues Packages Projects Releases Wiki Activity

feat: lazy electron download (#49328)

Browse Source 
* feat: lazy electron download

* better error messaging?

* add breaking changes script doc

* add binary download step to install instructions

* respect no binary env var
This commit is contained in:
Erick Zhao
2026-02-20 12:35:38 -08:00
committed by GitHub
parent 2b80f4ccc9
commit 19d0c072d5
4 changed files with 89 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/breaking-changes.md
View File

@@ -24,6 +24,35 @@ for more consistent output sizes.
## Planned Breaking API Changes (41.0)
### Behavior Changed: `electron` no longer downloads itself via `postinstall` script
Previously, the `electron` npm package would download the Electron binary from the repository's
GitHub Releases in the package's `postinstall` script.
With recent supply chain security attacks against the npm ecosystem with `postinstall` scripts as a
common attack vector, Electron will now download itself dynamically the first time that its main
`bin` script is run (e.g. via `npx electron`). With this change, you can now use Electron with the
npm `--ignore-scripts` flag. See [RFC #22](https://github.com/electron/rfcs/pull/22) for more context.
```sh
# won't install binary to `node_modules/electron`
npm install electron --save-dev --ignore-scripts
# will download the binary on demand before starting electron process
npx electron .
# subsequent runs will used the binary downloaded from the first run
npx electron .
```
If you need to download the Electron binary on-demand, you can now call the `install-electron` script,
which contains the exact same code from the former `postinstall` script.
```sh
npm install electron --save-dev --ignore-scripts
npx install-electron --no
```
### Behavior Changed: PDFs no longer create a separate WebContents
Previously, PDF resources created a separate guest [WebContents](https://www.electronjs.org/docs/latest/api/web-contents) for rendering. Now, PDFs are rendered within the same WebContents instead. If you have code to detect PDF resources, use the [frame tree](https://www.electronjs.org/docs/latest/api/web-frame-main) instead of WebContents.

43
docs/tutorial/installation.md
View File

@@ -11,6 +11,30 @@ npm install electron --save-dev
See the [Electron versioning doc][versioning] for info on how to
manage Electron versions in your apps.
## Binary download step
Under the hood, Electron's JavaScript API binds to a binary that contains its
implementations. This binary is crucial to the function of any Electron app, and
is downloaded by default the first time you run Electron in development mode
(i.e. `electron .`).
If you want to install the binary on demand instead, you can run the `install-electron` bin script
included in the `electron` package:
```sh
npx install-electron --no
```
If you want to install your project's dependencies but don't need to use
Electron functionality, you can set the `ELECTRON_SKIP_BINARY_DOWNLOAD` environment
variable to prevent the binary from being downloaded. For instance, this feature can
be useful in continuous integration environments when running unit tests that mock
out the `electron` module.
```sh
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install
```
## Running Electron ad-hoc
If you're in a pinch and would prefer to not use `npm install` in your local
@@ -49,7 +73,7 @@ value, plus additional environment variables depending on your host system's Nod
* [Node 10 and above][proxy-env-10]
* [Before Node 10][proxy-env]
## Custom Mirrors and Caches
## Custom mirrors and caches
During installation, the `electron` module will call out to
[`@electron/get`][electron-get] to download prebuilt binaries of
@@ -120,23 +144,6 @@ The cache contains the version's official zip file as well as a checksum, and is
│ └── electron-v15.3.1-darwin-x64.zip
```
## 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,
it is downloaded by default in the `postinstall` step every time you install `electron`
from the npm registry.
However, if you want to install your project's dependencies but don't need to use
Electron functionality, you can set the `ELECTRON_SKIP_BINARY_DOWNLOAD` environment
variable to prevent the binary from being downloaded. For instance, this feature can
be useful in continuous integration environments when running unit tests that mock
out the `electron` module.
```sh npm2yarn
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install
```
## Troubleshooting
When running `npm install electron`, some users occasionally encounter