mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

docs: remove quickstart (#45209)

Browse source 
Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Anny Yang <yangannyx@gmail.com>
This commit is contained in:
trop[bot] 2025-01-17 10:36:58 +01:00 • committed by GitHub
parent 8a64cdc0b1
commit 97fa059e1f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 12 additions and 525 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/README.md
View file

@ -21,7 +21,6 @@ an issue:
### Getting started ### Getting started
* [Introduction](tutorial/introduction.md) * [Introduction](tutorial/introduction.md)
* [Quick Start](tutorial/quick-start.md)
* [Process Model](tutorial/process-model.md) * [Process Model](tutorial/process-model.md)
### Learning the basics ### Learning the basics

7
docs/tutorial/keyboard-shortcuts.md
View file

@ -14,7 +14,7 @@ To configure a local keyboard shortcut, you need to specify an [`accelerator`][]
property when creating a [MenuItem][] within the [Menu][] module. property when creating a [MenuItem][] within the [Menu][] module.
Starting with a working application from the Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` to be: [tutorial starter code][tutorial-starter-code], update the `main.js` to be:
```fiddle docs/fiddles/features/keyboard-shortcuts/local ```fiddle docs/fiddles/features/keyboard-shortcuts/local
const { app, BrowserWindow, Menu, MenuItem } = require('electron/main') const { app, BrowserWindow, Menu, MenuItem } = require('electron/main')
@ -75,7 +75,7 @@ module to detect keyboard events even when the application does not have
keyboard focus. keyboard focus.
Starting with a working application from the Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` to be: [tutorial starter code][tutorial-starter-code], update the `main.js` to be:
```fiddle docs/fiddles/features/keyboard-shortcuts/global ```fiddle docs/fiddles/features/keyboard-shortcuts/global
const { app, BrowserWindow, globalShortcut } = require('electron/main') const { app, BrowserWindow, globalShortcut } = require('electron/main')
@ -144,7 +144,7 @@ is emitted before dispatching `keydown` and `keyup` events in the page. It can
be used to catch and handle custom shortcuts that are not visible in the menu. be used to catch and handle custom shortcuts that are not visible in the menu.
Starting with a working application from the Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the [tutorial starter code][tutorial-starter-code], update the `main.js` file with the
following lines: following lines:
```fiddle docs/fiddles/features/keyboard-shortcuts/interception-from-main ```fiddle docs/fiddles/features/keyboard-shortcuts/interception-from-main
@ -207,3 +207,4 @@ Mousetrap.bind('up up down down left right left right b a enter', () => {
[mousetrap]: https://github.com/ccampbell/mousetrap [mousetrap]: https://github.com/ccampbell/mousetrap
[dom-events]: https://developer.mozilla.org/en-US/docs/Web/Events [dom-events]: https://developer.mozilla.org/en-US/docs/Web/Events
[addEventListener-api]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener [addEventListener-api]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
[tutorial-starter-code]: tutorial-2-first-app.md#final-starter-code

4
docs/tutorial/process-model.md
View file

@ -86,7 +86,7 @@ The main process also controls your application's lifecycle through Electron's
that you can use to add custom application behavior (for instance, programmatically that you can use to add custom application behavior (for instance, programmatically
quitting your application, modifying the application dock, or showing an About panel). quitting your application, modifying the application dock, or showing an About panel).
As a practical example, the app shown in the [quick start guide][quick-start-lifecycle] As a practical example, the app shown in the [tutorial starter code][tutorial-lifecycle]
uses `app` APIs to create a more native application window experience. uses `app` APIs to create a more native application window experience.
```js title='main.js' ```js title='main.js'
@ -97,7 +97,7 @@ app.on('window-all-closed', () => {
``` ```
[app]: ../api/app.md [app]: ../api/app.md
[quick-start-lifecycle]: ../tutorial/quick-start.md#manage-your-windows-lifecycle [tutorial-lifecycle]: ../tutorial/tutorial-2-first-app.md#quit-the-app-when-all-windows-are-closed-windows--linux
### Native APIs ### Native APIs

513
docs/tutorial/quick-start.md
View file

@ -1,513 +0,0 @@
# Quick Start
This guide will step you through the process of creating a barebones Hello World app in
Electron, similar to [`electron/electron-quick-start`][quick-start].
By the end of this tutorial, your app will open a browser window that displays a web page
with information about which Chromium, Node.js, and Electron versions are running.
[quick-start]: https://github.com/electron/electron-quick-start
## Prerequisites
To use Electron, you need to install [Node.js][node-download]. We recommend that you
use the latest `LTS` version available.
> Please install Node.js using pre-built installers for your platform.
> You may encounter incompatibility issues with different development tools otherwise.
To check that Node.js was installed correctly, type the following commands in your
terminal client:
```sh
node -v
npm -v
```
The commands should print the versions of Node.js and npm accordingly.
**Note:** Since Electron embeds Node.js into its binary, the version of Node.js running
your code is unrelated to the version running on your system.
[node-download]: https://nodejs.org/en/download/
## Create your application
### Scaffold the project
Electron apps follow the same general structure as other Node.js projects.
Start by creating a folder and initializing an npm package.
```sh npm2yarn
mkdir my-electron-app && cd my-electron-app
npm init
```
The interactive `init` command will prompt you to set some fields in your config.
There are a few rules to follow for the purposes of this tutorial:
* `entry point` should be `main.js`.
* `author` and `description` can be any value, but are necessary for
[app packaging](#package-and-distribute-your-application).
Your `package.json` file should look something like this:
```json
{
"name": "my-electron-app",
"version": "1.0.0",
"description": "Hello World!",
"main": "main.js",
"author": "Jane Doe",
"license": "MIT"
}
```
Then, install the `electron` package into your app's `devDependencies`.
```sh npm2yarn
npm install --save-dev electron
```
> Note: If you're encountering any issues with installing Electron, please
> refer to the [Advanced Installation][advanced-installation] guide.
Finally, you want to be able to execute Electron. In the [`scripts`][package-scripts]
field of your `package.json` config, add a `start` command like so:
```json
{
"scripts": {
"start": "electron ."
}
}
```
This `start` command will let you open your app in development mode.
```sh npm2yarn
npm start
```
> Note: This script tells Electron to run on your project's root folder. At this stage,
> your app will immediately throw an error telling you that it cannot find an app to run.
[advanced-installation]: ./installation.md
[package-scripts]: https://docs.npmjs.com/cli/v7/using-npm/scripts
### Run the main process
The entry point of any Electron application is its `main` script. This script controls the
**main process**, which runs in a full Node.js environment and is responsible for
controlling your app's lifecycle, displaying native interfaces, performing privileged
operations, and managing renderer processes (more on that later).
During execution, Electron will look for this script in the [`main`][package-json-main]
field of the app's `package.json` config, which you should have configured during the
[app scaffolding](#scaffold-the-project) step.
To initialize the `main` script, create an empty file named `main.js` in the root folder
of your project.
> Note: If you run the `start` script again at this point, your app will no longer throw
> any errors! However, it won't do anything yet because we haven't added any code into
> `main.js`.
[package-json-main]: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#main
### Create a web page
Before we can create a window for our application, we need to create the content that
will be loaded into it. In Electron, each window displays web contents that can be loaded
from either a local HTML file or a remote URL.
For this tutorial, you will be doing the former. Create an `index.html` file in the root
folder of your project:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
<title>Hello World!</title>
</head>
<body>
<h1>Hello World!</h1>
We are using Node.js <span id="node-version"></span>,
Chromium <span id="chrome-version"></span>,
and Electron <span id="electron-version"></span>.
</body>
</html>
```
> Note: Looking at this HTML document, you can observe that the version numbers are
> missing from the body text. We'll manually insert them later using JavaScript.
### Opening your web page in a browser window
Now that you have a web page, load it into an application window. To do so, you'll
need two Electron modules:
* The [`app`][app] module, which controls your application's event lifecycle.
* The [`BrowserWindow`][browser-window] module, which creates and manages application
windows.
Because the main process runs Node.js, you can import these as [CommonJS][commonjs]
modules at the top of your `main.js` file:
```js
const { app, BrowserWindow } = require('electron')
```
Then, add a `createWindow()` function that loads `index.html` into a new `BrowserWindow`
instance.
```js
const createWindow = () => {
const win = new BrowserWindow({
width: 800,
height: 600
})
win.loadFile('index.html')
}
```
Next, call this `createWindow()` function to open your window.
In Electron, browser windows can only be created after the `app` module's
[`ready`][app-ready] event is fired. You can wait for this event by using the
[`app.whenReady()`][app-when-ready] API. Call `createWindow()` after `whenReady()`
resolves its Promise.
```js @ts-type={createWindow:()=>void}
app.whenReady().then(() => {
createWindow()
})
```
> Note: At this point, your Electron application should successfully
> open a window that displays your web page!
[app]: ../api/app.md
[browser-window]: ../api/browser-window.md
[commonjs]: https://nodejs.org/docs/latest/api/modules.html#modules_modules_commonjs_modules
[app-ready]: ../api/app.md#event-ready
[app-when-ready]: ../api/app.md#appwhenready
### Manage your window's lifecycle
Although you can now open a browser window, you'll need some additional boilerplate code
to make it feel more native to each platform. Application windows behave differently on
each OS, and Electron puts the responsibility on developers to implement these
conventions in their app.
In general, you can use the `process` global's [`platform`][node-platform] attribute
to run code specifically for certain operating systems.
#### Quit the app when all windows are closed (Windows & Linux)
On Windows and Linux, exiting all windows generally quits an application entirely.
To implement this, listen for the `app` module's [`'window-all-closed'`][window-all-closed]
event, and call [`app.quit()`][app-quit] if the user is not on macOS (`darwin`).
```js
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit()
})
```
[node-platform]: https://nodejs.org/api/process.html#process_process_platform
[window-all-closed]: ../api/app.md#event-window-all-closed
[app-quit]: ../api/app.md#appquit
#### Open a window if none are open (macOS)
Whereas Linux and Windows apps quit when they have no windows open, macOS apps generally
continue running even without any windows open, and activating the app when no windows
are available should open a new one.
To implement this feature, listen for the `app` module's [`activate`][activate]
event, and call your existing `createWindow()` method if no browser windows are open.
Because windows cannot be created before the `ready` event, you should only listen for
`activate` events after your app is initialized. Do this by attaching your event listener
from within your existing `whenReady()` callback.
[activate]: ../api/app.md#event-activate-macos
```js @ts-type={createWindow:()=>void}
app.whenReady().then(() => {
createWindow()
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) createWindow()
})
})
```
> Note: At this point, your window controls should be fully functional!
### Access Node.js from the renderer with a preload script
Now, the last thing to do is print out the version numbers for Electron and its
dependencies onto your web page.
Accessing this information is trivial to do in the main process through Node's
global `process` object. However, you can't just edit the DOM from the main
process because it has no access to the renderer's `document` context.
They're in entirely different processes!
> Note: If you need a more in-depth look at Electron processes, see the
> [Process Model][] document.
This is where attaching a **preload** script to your renderer comes in handy.
A preload script runs before the renderer process is loaded, and has access to both
renderer globals (e.g. `window` and `document`) and a Node.js environment.
Create a new script named `preload.js` as such:
```js
window.addEventListener('DOMContentLoaded', () => {
const replaceText = (selector, text) => {
const element = document.getElementById(selector)
if (element) element.innerText = text
}
for (const dependency of ['chrome', 'node', 'electron']) {
replaceText(`${dependency}-version`, process.versions[dependency])
}
})
```
The above code accesses the Node.js `process.versions` object and runs a basic `replaceText`
helper function to insert the version numbers into the HTML document.
To attach this script to your renderer process, pass in the path to your preload script
to the `webPreferences.preload` option in your existing `BrowserWindow` constructor.
```js
const { app, BrowserWindow } = require('electron')
// include the Node.js 'path' module at the top of your file
const path = require('node:path')
// modify your existing createWindow() function
const createWindow = () => {
const win = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})
win.loadFile('index.html')
}
// ...
```
There are two Node.js concepts that are used here:
* The [`__dirname`][dirname] string points to the path of the currently executing script
(in this case, your project's root folder).
* The [`path.join`][path-join] API joins multiple path segments together, creating a
combined path string that works across all platforms.
We use a path relative to the currently executing JavaScript file so that your relative
path will work in both development and packaged mode.
[Process Model]: ./process-model.md
[dirname]: https://nodejs.org/api/modules.html#modules_dirname
[path-join]: https://nodejs.org/api/path.html#path_path_join_paths
### Bonus: Add functionality to your web contents
At this point, you might be wondering how to add more functionality to your application.
For any interactions with your web contents, you want to add scripts to your
renderer process. Because the renderer runs in a normal web environment, you can add a
`<script>` tag right before your `index.html` file's closing `</body>` tag to include
any arbitrary scripts you want:
```html
<script src="./renderer.js"></script>
```
The code contained in `renderer.js` can then use the same JavaScript APIs and tooling
you use for typical front-end development, such as using [`webpack`][webpack] to bundle
and minify your code or [React][react] to manage your user interfaces.
[webpack]: https://webpack.js.org
[react]: https://reactjs.org
### Recap
After following the above steps, you should have a fully functional
Electron application that looks like this:
![Simplest Electron app](../images/simplest-electron-app.png)
<!--TODO(erickzhao): Remove the individual code blocks for static website -->
The full code is available below:
```js
// main.js
// Modules to control application life and create native browser window
const { app, BrowserWindow } = require('electron')
const path = require('node:path')
const createWindow = () => {
// Create the browser window.
const mainWindow = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})
// and load the index.html of the app.
mainWindow.loadFile('index.html')
// Open the DevTools.
// mainWindow.webContents.openDevTools()
}
// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
createWindow()
app.on('activate', () => {
// On macOS it's common to re-create a window in the app when the
// dock icon is clicked and there are no other windows open.
if (BrowserWindow.getAllWindows().length === 0) createWindow()
})
})
// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit()
})
// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and require them here.
```
```js
// preload.js
// All the Node.js APIs are available in the preload process.
// It has the same sandbox as a Chrome extension.
window.addEventListener('DOMContentLoaded', () => {
const replaceText = (selector, text) => {
const element = document.getElementById(selector)
if (element) element.innerText = text
}
for (const dependency of ['chrome', 'node', 'electron']) {
replaceText(`${dependency}-version`, process.versions[dependency])
}
})
```
```html
<!--index.html-->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
<title>Hello World!</title>
</head>
<body>
<h1>Hello World!</h1>
We are using Node.js <span id="node-version"></span>,
Chromium <span id="chrome-version"></span>,
and Electron <span id="electron-version"></span>.
<!-- You can also require other files to run in this process -->
<script src="./renderer.js"></script>
</body>
</html>
```
```fiddle docs/fiddles/quick-start
```
To summarize all the steps we've done:
* We bootstrapped a Node.js application and added Electron as a dependency.
* We created a `main.js` script that runs our main process, which controls our app
and runs in a Node.js environment. In this script, we used Electron's `app` and
`BrowserWindow` modules to create a browser window that displays web content
in a separate process (the renderer).
* In order to access certain Node.js functionality in the renderer, we attached
a preload script to our `BrowserWindow` constructor.
## Package and distribute your application
The fastest way to distribute your newly created app is using
[Electron Forge](https://www.electronforge.io).
:::info
To build an RPM package for Linux, you will need to [install its required system dependencies](https://www.electronforge.io/config/makers/rpm).
:::
1. Add a description to your `package.json` file, otherwise rpmbuild will fail. Blank description are not valid.
2. Add Electron Forge as a development dependency of your app, and use its `import` command to set up
Forge's scaffolding:
```sh npm2yarn
npm install --save-dev @electron-forge/cli
npx electron-forge import
✔ Checking your system
✔ Initializing Git Repository
✔ Writing modified package.json file
✔ Installing dependencies
✔ Writing modified package.json file
✔ Fixing .gitignore
We have ATTEMPTED to convert your app to be in a format that electron-forge understands.
Thanks for using "electron-forge"!!!
```
3. Create a distributable using Forge's `make` command:
```sh npm2yarn
npm run make
> my-electron-app@1.0.0 make /my-electron-app
> electron-forge make
✔ Checking your system
✔ Resolving Forge Config
We need to package your application before we can make it
✔ Preparing to Package Application for arch: x64
✔ Preparing native dependencies
✔ Packaging Application
Making for the following targets: zip
✔ Making for target: zip - On platform: darwin - For arch: x64
```
Electron Forge creates the `out` folder where your package will be located:
```plain
// Example for macOS
out/
├── out/make/zip/darwin/x64/my-electron-app-darwin-x64-1.0.0.zip
├── ...
└── out/my-electron-app-darwin-x64/my-electron-app.app/Contents/MacOS/my-electron-app
```

2
docs/tutorial/windows-arm.md
View file

@ -8,7 +8,7 @@ If your app doesn't use any native modules, then it's really easy to create an A
1. Make sure that your app's `node_modules` directory is empty. 1. Make sure that your app's `node_modules` directory is empty.
2. Using a _Command Prompt_, run `set npm_config_arch=arm64` before running `npm install`/`yarn install` as usual. 2. Using a _Command Prompt_, run `set npm_config_arch=arm64` before running `npm install`/`yarn install` as usual.
3. [If you have Electron installed as a development dependency](quick-start.md#prerequisites), npm will download and unpack the arm64 version. You can then package and distribute your app as normal. 3. [If you have Electron installed as a development dependency](tutorial-2-first-app.md#initializing-your-npm-project), npm will download and unpack the arm64 version. You can then package and distribute your app as normal.
## General considerations ## General considerations

10
docs/tutorial/windows-taskbar.md
View file

@ -57,7 +57,7 @@ To set user tasks for your application, you can use
##### Set user tasks ##### Set user tasks
Starting with a working application from the Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the [tutorial starter code][tutorial-starter-code], update the `main.js` file with the
following lines: following lines:
```js ```js
@ -121,7 +121,7 @@ To set thumbnail toolbar in your application, you need to use
##### Set thumbnail toolbar ##### Set thumbnail toolbar
Starting with a working application from the Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the [tutorial starter code][tutorial-starter-code], update the `main.js` file with the
following lines: following lines:
```js ```js
@ -185,7 +185,7 @@ To set the overlay icon for a window, you need to use the
#### Example #### Example
Starting with a working application from the Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the [tutorial starter code][tutorial-starter-code], update the `main.js` file with the
following lines: following lines:
```js ```js
@ -214,7 +214,7 @@ To flash the BrowserWindow taskbar button, you need to use the
#### Example #### Example
Starting with a working application from the Starting with a working application from the
[Quick Start Guide](quick-start.md), update the `main.js` file with the [tutorial starter code][tutorial-starter-code], update the `main.js` file with the
following lines: following lines:
```js ```js
@ -231,10 +231,10 @@ In the above example, it is called when the window comes into focus,
but you might use a timeout or some other event to disable it. but you might use a timeout or some other event to disable it.
[msdn-flash-frame]: https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-flashwindow#remarks [msdn-flash-frame]: https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-flashwindow#remarks
[setthumbarbuttons]: ../api/browser-window.md#winsetthumbarbuttonsbuttons-windows [setthumbarbuttons]: ../api/browser-window.md#winsetthumbarbuttonsbuttons-windows
[setusertaskstasks]: ../api/app.md#appsetusertaskstasks-windows [setusertaskstasks]: ../api/app.md#appsetusertaskstasks-windows
[setoverlayicon]: ../api/browser-window.md#winsetoverlayiconoverlay-description-windows [setoverlayicon]: ../api/browser-window.md#winsetoverlayiconoverlay-description-windows
[flashframe]: ../api/browser-window.md#winflashframeflag [flashframe]: ../api/browser-window.md#winflashframeflag
[recent-documents]: ./recent-documents.md [recent-documents]: ./recent-documents.md
[progress-bar]: ./progress-bar.md [progress-bar]: ./progress-bar.md
[tutorial-starter-code]: ../tutorial/tutorial-2-first-app.md#final-starter-code