chore: cleanup whitespace in docs (#26356)
This commit is contained in:
David Sanders
GitHub
parent
3814a56d48
commit
43dbd1bdf8
45 changed files with 129 additions and 72 deletions
|
|
@ -9,6 +9,7 @@ To distribute your app with Electron, you need to package and rebrand it. The ea
|
|||
These tools will take care of all the steps you need to take to end up with a distributable Electron applications, such as packaging your application, rebranding the executable, setting the right icons and optionally creating installers.
|
||||
|
||||
## Manual distribution
|
||||
|
||||
You can also choose to manually get your app ready for distribution. The steps needed to do this are outlined below.
|
||||
|
||||
To distribute your app with Electron, you need to download Electron's [prebuilt
|
||||
|
|
@ -143,16 +144,16 @@ we appreciate your help.
|
|||
|
||||
3. Set the following Environment Variables:
|
||||
|
||||
* `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub
|
||||
* `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` -
|
||||
the place where you'll upload Node.js headers as well as symbols
|
||||
* `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset
|
||||
and `surf-build` will do CI-type checks, appropriate to run for every
|
||||
pull request.
|
||||
* `CI` - Set to `true` or else it will fail
|
||||
* `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN`
|
||||
* `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues
|
||||
* `TARGET_ARCH` - set to `ia32` or `x64`
|
||||
* `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub
|
||||
* `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` -
|
||||
the place where you'll upload Node.js headers as well as symbols
|
||||
* `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset
|
||||
and `surf-build` will do CI-type checks, appropriate to run for every
|
||||
pull request.
|
||||
* `CI` - Set to `true` or else it will fail
|
||||
* `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN`
|
||||
* `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues
|
||||
* `TARGET_ARCH` - set to `ia32` or `x64`
|
||||
|
||||
4. In `script/upload.py`, you _must_ set `ELECTRON_REPO` to your fork (`MYORG/electron`),
|
||||
especially if you are a contributor to Electron proper.
|
||||
|
|
|
|||
|
|
@ -192,4 +192,3 @@ and should be shipped together with the `app.asar` archive.
|
|||
[electron-packager]: https://github.com/electron/electron-packager
|
||||
[electron-forge]: https://github.com/electron-userland/electron-forge
|
||||
[electron-builder]: https://github.com/electron-userland/electron-builder
|
||||
|
||||
|
|
|
|||
|
|
@ -67,4 +67,3 @@ contextBridge.exposeInMainWorld('myAPI', {
|
|||
loadPreferences: () => ipcRenderer.invoke('load-prefs')
|
||||
})
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -124,6 +124,7 @@ Depending on the received event, we update the
|
|||
property to apply the desired theme on the system's native UI elements
|
||||
(e.g. context menus) and propagate the preferred color scheme to the Renderer
|
||||
process:
|
||||
|
||||
* Upon receiving `dark-mode:toggle`, we check if the dark theme is currently
|
||||
active using the `nativeTheme.shouldUseDarkColors` property, and set the
|
||||
`themeSource` to the opposite theme.
|
||||
|
|
|
|||
|
|
@ -29,7 +29,6 @@ $ code electron-quick-start
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
### 3. Debugging
|
||||
|
||||
Set some breakpoints in `main.js`, and start debugging in the [Debug View](https://code.visualstudio.com/docs/editor/debugging). You should be able to hit the breakpoints.
|
||||
|
|
|
|||
|
|
@ -29,6 +29,7 @@ Using the [React Developer Tools][react-devtools] as example:
|
|||
* on macOS it is `~/Library/Application Support/Google/Chrome/Default/Extensions`.
|
||||
1. Pass the location of the extension to `BrowserWindow.addDevToolsExtension`
|
||||
API, for the React Developer Tools, it is something like:
|
||||
|
||||
```javascript
|
||||
const path = require('path')
|
||||
const os = require('os')
|
||||
|
|
|
|||
|
|
@ -48,7 +48,6 @@ Below is a table explicitly mapping types of changes to their corresponding cate
|
|||
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
|
||||
| Chromium version updates | | fix-related chromium patches |
|
||||
|
||||
|
||||
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
|
||||
|
||||
# Stabilization Branches
|
||||
|
|
@ -118,6 +117,7 @@ A few examples of how various semver ranges will pick up new releases:
|
|||
|
||||
|
||||
# Missing Features: Alphas
|
||||
|
||||
Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.
|
||||
|
||||
As a future consideration, we may introduce one or both of the following:
|
||||
|
|
@ -125,6 +125,7 @@ As a future consideration, we may introduce one or both of the following:
|
|||
* alpha releases that have looser stability constraints to betas; for example it would be allowable to admit new features while a stability channel is in _alpha_
|
||||
|
||||
# Feature Flags
|
||||
|
||||
Feature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or **soft branch** must have the following properties:
|
||||
|
||||
* it is enabled/disabled either at runtime, or build-time; we do not support the concept of a request-scoped feature flag
|
||||
|
|
|
|||
|
|
@ -3,11 +3,13 @@
|
|||
## Preparing
|
||||
|
||||
### Paid Applications Agreement
|
||||
|
||||
If you haven't already, you’ll need to sign the Paid Applications Agreement and set up your banking and tax information in iTunes Connect.
|
||||
|
||||
[iTunes Connect Developer Help: Agreements, tax, and banking overview](https://help.apple.com/itunes-connect/developer/#/devb6df5ee51)
|
||||
|
||||
### Create Your In-App Purchases
|
||||
|
||||
Then, you'll need to configure your in-app purchases in iTunes Connect, and include details such as name, pricing, and description that highlights the features and functionality of your in-app purchase.
|
||||
|
||||
[iTunes Connect Developer Help: Create an in-app purchase](https://help.apple.com/itunes-connect/developer/#/devae49fb316)
|
||||
|
|
|
|||
|
|
@ -45,6 +45,7 @@ value, plus additional environment variables depending on your host system's Nod
|
|||
* [Before Node 10][proxy-env]
|
||||
|
||||
## Custom Mirrors and Caches
|
||||
|
||||
During installation, the `electron` module will call out to
|
||||
[`@electron/get`][electron-get] to download prebuilt binaries of
|
||||
Electron for your platform. It will do so by contacting GitHub's
|
||||
|
|
@ -55,6 +56,7 @@ 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
|
||||
|
||||
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`
|
||||
is composed as follows:
|
||||
|
|
@ -84,6 +86,7 @@ The above configuration will download from URLs such as
|
|||
`https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip`.
|
||||
|
||||
#### 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
|
||||
that cache folder to provide custom builds of Electron or to avoid making contact
|
||||
|
|
@ -126,12 +129,14 @@ a text file. A typical cache might look like this:
|
|||
```
|
||||
|
||||
## Skip binary download
|
||||
|
||||
When installing the `electron` NPM package, it automatically downloads the electron binary.
|
||||
|
||||
This can sometimes be unnecessary, e.g. in a CI environment, when testing another component.
|
||||
|
||||
To prevent the binary from being downloaded when you install all npm dependencies you can set the environment variable `ELECTRON_SKIP_BINARY_DOWNLOAD`.
|
||||
E.g.:
|
||||
|
||||
```sh
|
||||
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install
|
||||
```
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ detection can be implemented in the Renderer process using the
|
|||
attribute, part of standard HTML5 API.
|
||||
|
||||
The `navigator.onLine` attribute returns:
|
||||
|
||||
* `false` if all network requests are guaranteed to fail (e.g. when disconnected from the network).
|
||||
* `true` in all other cases.
|
||||
|
||||
|
|
|
|||
|
|
@ -46,8 +46,8 @@ at once, consider the [Chrome Tracing](https://www.chromium.org/developers/how-t
|
|||
|
||||
### Recommended Reading
|
||||
|
||||
* [Get Started With Analyzing Runtime Performance][chrome-devtools-tutorial]
|
||||
* [Talk: "Visual Studio Code - The First Second"][vscode-first-second]
|
||||
* [Get Started With Analyzing Runtime Performance][chrome-devtools-tutorial]
|
||||
* [Talk: "Visual Studio Code - The First Second"][vscode-first-second]
|
||||
|
||||
## Checklist
|
||||
|
||||
|
|
@ -264,7 +264,6 @@ core Node.js modules (like `fs` or `child_process`) offer a synchronous or an
|
|||
asynchronous version, you should prefer the asynchronous and non-blocking
|
||||
variant.
|
||||
|
||||
|
||||
## 4) Blocking the renderer process
|
||||
|
||||
Since Electron ships with a current version of Chrome, you can make use of the
|
||||
|
|
@ -301,7 +300,6 @@ some caveats to consider – consult Electron's
|
|||
for any operation that requires a lot of CPU power for an extended period of
|
||||
time.
|
||||
|
||||
|
||||
## 5) Unnecessary polyfills
|
||||
|
||||
One of Electron's great benefits is that you know exactly which engine will
|
||||
|
|
@ -340,7 +338,6 @@ If you're using a transpiler/compiler like TypeScript, examine its configuration
|
|||
and ensure that you're targeting the latest ECMAScript version supported by
|
||||
Electron.
|
||||
|
||||
|
||||
## 6) Unnecessary or blocking network requests
|
||||
|
||||
Avoid fetching rarely changing resources from the internet if they could easily
|
||||
|
|
|
|||
|
|
@ -12,6 +12,7 @@ The `repl` module provides a REPL implementation that can be accessed using:
|
|||
```sh
|
||||
./node_modules/.bin/electron --interactive
|
||||
```
|
||||
|
||||
* Assuming you have `electron` or `electron-prebuilt` installed globally:
|
||||
|
||||
```sh
|
||||
|
|
|
|||
|
|
@ -56,7 +56,6 @@ is your own code. Common web vulnerabilities, such as Cross-Site Scripting (XSS)
|
|||
have a higher security impact on Electron applications hence it is highly recommended
|
||||
to adopt secure software development best practices and perform security testing.
|
||||
|
||||
|
||||
## Isolation For Untrusted Content
|
||||
|
||||
A security issue exists whenever you receive code from an untrusted source (e.g.
|
||||
|
|
@ -150,7 +149,6 @@ browserWindow.loadURL('https://example.com')
|
|||
<link rel="stylesheet" href="https://example.com/style.css">
|
||||
```
|
||||
|
||||
|
||||
## 2) Do not enable Node.js Integration for Remote Content
|
||||
|
||||
_This recommendation is the default behavior in Electron since 5.0.0._
|
||||
|
|
@ -225,7 +223,6 @@ window.readConfig = function () {
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
## 3) Enable Context Isolation for Remote Content
|
||||
|
||||
Context isolation is an Electron feature that allows developers to run code
|
||||
|
|
@ -244,7 +241,6 @@ prevent the use of Node primitives, `contextIsolation` must also be used.
|
|||
For more information on what `contextIsolation` is and how to enable it please
|
||||
see our dedicated [Context Isolation](context-isolation.md) document.
|
||||
|
||||
|
||||
## 4) Handle Session Permission Requests From Remote Content
|
||||
|
||||
You may have seen permission requests while using Chrome: They pop up whenever
|
||||
|
|
@ -283,7 +279,6 @@ session
|
|||
})
|
||||
```
|
||||
|
||||
|
||||
## 5) Do Not Disable WebSecurity
|
||||
|
||||
_Recommendation is Electron's default_
|
||||
|
|
@ -302,6 +297,7 @@ Disabling `webSecurity` will disable the same-origin policy and set
|
|||
the execution of insecure code from different domains.
|
||||
|
||||
### How?
|
||||
|
||||
```js
|
||||
// Bad
|
||||
const mainWindow = new BrowserWindow({
|
||||
|
|
@ -324,7 +320,6 @@ const mainWindow = new BrowserWindow()
|
|||
<webview src="page.html"></webview>
|
||||
```
|
||||
|
||||
|
||||
## 6) Define a Content Security Policy
|
||||
|
||||
A Content Security Policy (CSP) is an additional layer of protection against
|
||||
|
|
@ -381,7 +376,6 @@ on a page directly in the markup using a `<meta>` tag:
|
|||
<meta http-equiv="Content-Security-Policy" content="default-src 'none'">
|
||||
```
|
||||
|
||||
|
||||
## 7) Do Not Set `allowRunningInsecureContent` to `true`
|
||||
|
||||
_Recommendation is Electron's default_
|
||||
|
|
@ -415,7 +409,6 @@ const mainWindow = new BrowserWindow({
|
|||
const mainWindow = new BrowserWindow({})
|
||||
```
|
||||
|
||||
|
||||
## 8) Do Not Enable Experimental Features
|
||||
|
||||
_Recommendation is Electron's default_
|
||||
|
|
@ -448,7 +441,6 @@ const mainWindow = new BrowserWindow({
|
|||
const mainWindow = new BrowserWindow({})
|
||||
```
|
||||
|
||||
|
||||
## 9) Do Not Use `enableBlinkFeatures`
|
||||
|
||||
_Recommendation is Electron's default_
|
||||
|
|
@ -466,6 +458,7 @@ ramifications are, and how it impacts the security of your application. Under
|
|||
no circumstances should you enable features speculatively.
|
||||
|
||||
### How?
|
||||
|
||||
```js
|
||||
// Bad
|
||||
const mainWindow = new BrowserWindow({
|
||||
|
|
@ -480,7 +473,6 @@ const mainWindow = new BrowserWindow({
|
|||
const mainWindow = new BrowserWindow()
|
||||
```
|
||||
|
||||
|
||||
## 10) Do Not Use `allowpopups`
|
||||
|
||||
_Recommendation is Electron's default_
|
||||
|
|
@ -508,7 +500,6 @@ you know it needs that feature.
|
|||
<webview src="page.html"></webview>
|
||||
```
|
||||
|
||||
|
||||
## 11) Verify WebView Options Before Creation
|
||||
|
||||
A WebView created in a renderer process that does not have Node.js integration
|
||||
|
|
@ -660,6 +651,7 @@ leveraged to execute arbitrary commands.
|
|||
const { shell } = require('electron')
|
||||
shell.openExternal(USER_CONTROLLED_DATA_HERE)
|
||||
```
|
||||
|
||||
```js
|
||||
// Good
|
||||
const { shell } = require('electron')
|
||||
|
|
@ -730,7 +722,6 @@ const mainWindow = new BrowserWindow({
|
|||
> from Electron 10. For prior versions, you need to explicitly disable
|
||||
> the `remote` module by the means above.
|
||||
|
||||
|
||||
## 16) Filter the `remote` module
|
||||
|
||||
If you cannot disable the `remote` module, you should filter the globals,
|
||||
|
|
@ -816,7 +807,6 @@ to fix issues before publishing them. Your application will be more secure if
|
|||
it is running a recent version of Electron (and thus, Chromium and Node.js) for
|
||||
which potential security issues are not as widely known.
|
||||
|
||||
|
||||
[browser-window]: ../api/browser-window.md
|
||||
[browser-view]: ../api/browser-view.md
|
||||
[webview-tag]: ../api/webview-tag.md
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@ If you're looking for programming help,
|
|||
for answers to questions,
|
||||
or to join in discussion with other developers who use Electron,
|
||||
you can interact with the community in these locations:
|
||||
|
||||
- [`Electron's Discord`](https://discord.com/invite/electron) has channels for:
|
||||
- Getting help
|
||||
- Ecosystem apps like [Electron Forge](https://github.com/electron-userland/electron-forge) and [Electron Fiddle](https://github.com/electron/fiddle)
|
||||
|
|
@ -62,6 +63,7 @@ threshold, we will attempt to support backwards compatibility beyond two version
|
|||
until the maintainers feel the maintenance burden is too high to continue doing so.
|
||||
|
||||
### Currently supported versions
|
||||
|
||||
- 10.x.y
|
||||
- 9.x.y
|
||||
- 8.x.y
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
If your app runs with Electron 6.0.8 or later, you can now build it for Windows 10 on Arm. This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts.
|
||||
|
||||
## Running a basic app
|
||||
|
||||
If your app doesn't use any native modules, then it's really easy to create an Arm version of your app.
|
||||
|
||||
1. Make sure that your app's `node_modules` directory is empty.
|
||||
|
|
@ -26,17 +27,21 @@ if (process.arch === 'x64') {
|
|||
If you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of `npm_config_arch` in the environment, rather than relying on the current process arch.
|
||||
|
||||
### Native modules
|
||||
|
||||
If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built `.dll` or `.lib` files provided or referenced by the native module are available for Windows on Arm.
|
||||
|
||||
### Testing your app
|
||||
|
||||
To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location.
|
||||
|
||||
## Development prerequisites
|
||||
|
||||
### Node.js/node-gyp
|
||||
|
||||
[Node.js v12.9.0 or later is recommended.](https://nodejs.org/en/) If updating to a new version of Node is undesirable, you can instead [update npm's copy of node-gyp manually](https://github.com/nodejs/node-gyp/wiki/Updating-npm's-bundled-node-gyp) to version 5.0.2 or later, which contains the required changes to compile native modules for Arm.
|
||||
|
||||
### Visual Studio 2017
|
||||
|
||||
Visual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's [Visual Studio Dev Essentials program](https://visualstudio.microsoft.com/dev-essentials/). After installation, you can add the Arm-specific components by running the following from a _Command Prompt_:
|
||||
|
||||
```powershell
|
||||
|
|
@ -49,6 +54,7 @@ vs_installer.exe ^
|
|||
```
|
||||
|
||||
#### Creating a cross-compilation command prompt
|
||||
|
||||
Setting `npm_config_arch=arm64` in the environment creates the correct arm64 `.obj` files, but the standard _Developer Command Prompt for VS 2017_ will use the x64 linker. To fix this:
|
||||
|
||||
1. Duplicate the _x64_x86 Cross Tools Command Prompt for VS 2017_ shortcut (e.g. by locating it in the start menu, right clicking, selecting _Open File Location_, copying and pasting) to somewhere convenient.
|
||||
|
|
@ -76,8 +82,8 @@ By default, `node-gyp` unpacks Electron's node headers and downloads the x86 and
|
|||
|
||||
Substitute `6.0.9` for the version you're using.
|
||||
|
||||
|
||||
## Cross-compiling native modules
|
||||
|
||||
After completing all of the above, open your cross-compilation command prompt and run `set npm_config_arch=arm64`. Then use `npm install` to build your project as normal. As with cross-compiling x86 modules, you may need to remove `node_modules` to force recompilation of native modules if they were previously compiled for another architecture.
|
||||
|
||||
## Debugging native modules
|
||||
|
|
@ -92,4 +98,5 @@ Debugging native modules can be done with Visual Studio 2017 (running on your de
|
|||
6. Once attached, set any appropriate breakpoints and resume JavaScript execution using Chrome's [remote tools for Node](debugging-main-process.md).
|
||||
|
||||
## Getting additional help
|
||||
|
||||
If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please [file an issue](../development/issues.md) with "Windows on Arm" in the title.
|
||||
|
|
|
|||
|
|
@ -114,6 +114,7 @@ Another important limitation is that the compiled AppX package still contains a
|
|||
win32 executable - and will therefore not run on Xbox, HoloLens, or Phones.
|
||||
|
||||
## Optional: Add UWP Features using a BackgroundTask
|
||||
|
||||
You can pair your Electron app up with an invisible UWP background task that
|
||||
gets to make full use of Windows 10 features - like push notifications,
|
||||
Cortana integration, or live tiles.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue