diff --git a/docs/latest/.sha b/docs/latest/.sha index 33dbe9847..2afe2eca4 100644 --- a/docs/latest/.sha +++ b/docs/latest/.sha @@ -1 +1 @@ -6ee299c9eec451d1efcab4be09c3b3e4a028d2c9 \ No newline at end of file +f8479ece3d5a9b8338c9b084aba7f79e0be34d5d \ No newline at end of file diff --git a/docs/latest/faq.md b/docs/latest/faq.md index 44fbe4572..00dd57807 100644 --- a/docs/latest/faq.md +++ b/docs/latest/faq.md @@ -19,19 +19,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/latest/tutorial/installation.md b/docs/latest/tutorial/installation.md index d93a83b9f..95bcd3f39 100644 --- a/docs/latest/tutorial/installation.md +++ b/docs/latest/tutorial/installation.md @@ -33,12 +33,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 @@ -67,7 +67,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` @@ -102,7 +102,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 @@ -127,7 +127,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/latest/tutorial/tutorial-2-first-app.md b/docs/latest/tutorial/tutorial-2-first-app.md index 943764a96..9bd6f0ff8 100644 --- a/docs/latest/tutorial/tutorial-2-first-app.md +++ b/docs/latest/tutorial/tutorial-2-first-app.md @@ -55,14 +55,27 @@ There are a few rules to follow for the purposes of this tutorial: - _author_, _license_, and _description_ can be any value, but will be necessary for [packaging][packaging] later on. +:::caution Install dependencies with a regular `node_modules` folder + +Electron's packaging toolchain requires the `node_modules` folder to be physically on disk in the +way that npm installs Node dependencies. By default, [Yarn Berry](https://yarnpkg.com/) and +[pnpm](http://pnpm.io/) both use alternative installation strategies. + +Therefore, you must set [`nodeLinker: node-modules`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) +in Yarn or [`nodeLinker: hoisted`](https://pnpm.io/settings#nodelinker) in pnpm if you are using +those package managers. + +::: + 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 +83,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