docs: revised version of the quick start guide (#25760)
This commit is contained in:
Antonio
GitHub
parent
b194030a34
commit
8dfb1cf78f
18 changed files with 316 additions and 408 deletions
|
|
@ -23,20 +23,20 @@ an issue:
|
|||
* [Setting up Windows](tutorial/development-environment.md#setting-up-windows)
|
||||
* [Setting up Linux](tutorial/development-environment.md#setting-up-linux)
|
||||
* [Choosing an Editor](tutorial/development-environment.md#a-good-editor)
|
||||
* [Creating your First App](tutorial/first-app.md)
|
||||
* [Installing Electron](tutorial/first-app.md#installing-electron)
|
||||
* [Electron Development in a Nutshell](tutorial/first-app.md#electron-development-in-a-nutshell)
|
||||
* [Running Your App](tutorial/first-app.md#running-your-app)
|
||||
* [Creating your First App](tutorial/quick-start.md)
|
||||
* [Prerequisites](tutorial/quick-start.md#prerequisites)
|
||||
* [Create a basic application](tutorial/quick-start.md#create-a-basic-application)
|
||||
* [Package and distribute the application](tutorial/quick-start.md#package-and-distribute-the-application)
|
||||
* [Boilerplates and CLIs](tutorial/boilerplates-and-clis.md)
|
||||
* [Boilerplate vs CLI](tutorial/boilerplates-and-clis.md#boilerplate-vs-cli)
|
||||
* [electron-forge](tutorial/boilerplates-and-clis.md#electron-forge)
|
||||
* [electron-builder](tutorial/boilerplates-and-clis.md#electron-builder)
|
||||
* [electron-react-boilerplate](tutorial/boilerplates-and-clis.md#electron-react-boilerplate)
|
||||
* [Other Tools and Boilerplates](tutorial/boilerplates-and-clis.md#other-tools-and-boilerplates)
|
||||
* [Application Architecture](tutorial/application-architecture.md)
|
||||
* [Main and Renderer Processes](tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
* [Using Electron's APIs](tutorial/application-architecture.md#using-electron-apis)
|
||||
* [Using Node.js APIs](tutorial/application-architecture.md#using-nodejs-apis)
|
||||
* [Application Architecture](tutorial/quick-start.md#application-architecture)
|
||||
* [Main and Renderer Processes](tutorial/quick-start.md#main-and-renderer-processes)
|
||||
* [Electron API](tutorial/quick-start.md#electron-api)
|
||||
* [Node.js API](tutorial/quick-start.md#nodejs-api)
|
||||
* [Using Native Node.js Modules](tutorial/using-native-node-modules.md)
|
||||
* [Performance Strategies](tutorial/performance.md)
|
||||
* Adding Features to Your App
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ either process type.
|
|||
|
||||
The basic rule is: if a module is [GUI][gui] or low-level system related, then
|
||||
it should be only available in the main process. You need to be familiar with
|
||||
the concept of [main process vs. renderer process](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
the concept of [main process vs. renderer process](../tutorial/quick-start.md#main-and-renderer-processes)
|
||||
scripts to be able to use those modules.
|
||||
|
||||
The main process script is like a normal Node.js script:
|
||||
|
|
@ -43,7 +43,7 @@ extra ability to use node modules if `nodeIntegration` is enabled:
|
|||
</html>
|
||||
```
|
||||
|
||||
To run your app, read [Run your app](../tutorial/first-app.md#running-your-app).
|
||||
To run your app, read [Run your app](../tutorial/quick-start.md#run-your-application).
|
||||
|
||||
## Destructuring assignment
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a button in the touch bar for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarButton(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a color picker in the touch bar for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarColorPicker(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a group in the touch bar for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarGroup(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a label in the touch bar for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarLabel(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -7,6 +7,6 @@
|
|||
>
|
||||
> Note: Only one instance of this class can be added per TouchBar.
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarOtherItemsProxy()`
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a popover in the touch bar for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarPopover(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a scrubber (a scrollable selector)
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarScrubber(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a segmented control (a button group) where one button has a selected state
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarSegmentedControl(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a slider in the touch bar for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarSlider(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create a spacer between two items in the touch bar for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBarSpacer(options)`
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> Create TouchBar layouts for native macOS applications
|
||||
|
||||
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
### `new TouchBar(options)`
|
||||
|
||||
|
|
|
|||
BIN
docs/images/simplest-electron-app.png
Normal file
BIN
docs/images/simplest-electron-app.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 116 KiB |
|
|
@ -1,147 +0,0 @@
|
|||
# Electron Application Architecture
|
||||
|
||||
Before we can dive into Electron's APIs, we need to discuss the two process
|
||||
types available in Electron. They are fundamentally different and important to
|
||||
understand.
|
||||
|
||||
## Main and Renderer Processes
|
||||
|
||||
In Electron, the process that runs `package.json`'s `main` script is called
|
||||
__the main process__. The script that runs in the main process can display a
|
||||
GUI by creating web pages. An Electron app always has one main process, but
|
||||
never more.
|
||||
|
||||
Since Electron uses Chromium for displaying web pages, Chromium's
|
||||
multi-process architecture is also used. Each web page in Electron runs in
|
||||
its own process, which is called __the renderer process__.
|
||||
|
||||
In normal browsers, web pages usually run in a sandboxed environment and are not
|
||||
allowed access to native resources. Electron users, however, have the power to
|
||||
use Node.js APIs in web pages allowing lower level operating system
|
||||
interactions.
|
||||
|
||||
### Differences Between Main Process and Renderer Process
|
||||
|
||||
The main process creates web pages by creating `BrowserWindow` instances. Each
|
||||
`BrowserWindow` instance runs the web page in its own renderer process. When a
|
||||
`BrowserWindow` instance is destroyed, the corresponding renderer process
|
||||
is also terminated.
|
||||
|
||||
The main process manages all web pages and their corresponding renderer
|
||||
processes. Each renderer process is isolated and only cares about the web page
|
||||
running in it.
|
||||
|
||||
In web pages, calling native GUI related APIs is not allowed because managing
|
||||
native GUI resources in web pages is very dangerous and it is easy to leak
|
||||
resources. If you want to perform GUI operations in a web page, the renderer
|
||||
process of the web page must communicate with the main process to request that
|
||||
the main process perform those operations.
|
||||
|
||||
> #### Aside: Communication Between Processes
|
||||
> In Electron, communicating between the main process and renderer processes,
|
||||
> is done through the [`ipcRenderer`](../api/ipc-renderer.md) and
|
||||
> [`ipcMain`](../api/ipc-main.md) modules. There is also an FAQ entry on [how
|
||||
> to share data between web pages][share-data].
|
||||
|
||||
|
||||
## Using Electron APIs
|
||||
|
||||
Electron offers a number of APIs that support the development of a desktop
|
||||
application in both the main process and the renderer process. In both
|
||||
processes, you'd access Electron's APIs by requiring its included module:
|
||||
|
||||
```javascript
|
||||
const electron = require('electron')
|
||||
```
|
||||
|
||||
All Electron APIs are assigned a process type. Many of them can only be
|
||||
used from the main process, some of them only from a renderer process,
|
||||
some from both. The documentation for each individual API will
|
||||
state which process it can be used from.
|
||||
|
||||
A window in Electron is for instance created using the `BrowserWindow`
|
||||
class. It is only available in the main process.
|
||||
|
||||
```javascript
|
||||
// This will work in the main process, but be `undefined` in a
|
||||
// renderer process:
|
||||
const { BrowserWindow } = require('electron')
|
||||
|
||||
const win = new BrowserWindow()
|
||||
```
|
||||
|
||||
Since communication between the processes is possible, a renderer process
|
||||
can call upon the main process to perform tasks through IPC.
|
||||
|
||||
```javascript
|
||||
// In the main process:
|
||||
const { ipcMain } = require('electron')
|
||||
|
||||
ipcMain.handle('perform-action', (event, ...args) => {
|
||||
// ... do something on behalf of the renderer ...
|
||||
})
|
||||
|
||||
// In the renderer process:
|
||||
const { ipcRenderer } = require('electron')
|
||||
|
||||
ipcRenderer.invoke('perform-action', ...args)
|
||||
```
|
||||
|
||||
Note that code in the renderer may not be trustworthy, so it's important
|
||||
to carefully validate in the main process requests that come from renderers,
|
||||
especially if they host third-party content.
|
||||
|
||||
## Using Node.js APIs
|
||||
|
||||
Electron exposes full access to Node.js both in the main and the renderer
|
||||
process. This has two important implications:
|
||||
|
||||
1) All APIs available in Node.js are available in Electron. Calling the
|
||||
following code from an Electron app works:
|
||||
|
||||
```javascript
|
||||
const fs = require('fs')
|
||||
|
||||
const root = fs.readdirSync('/')
|
||||
|
||||
// This will print all files at the root-level of the disk,
|
||||
// either '/' or 'C:\'.
|
||||
console.log(root)
|
||||
```
|
||||
|
||||
As you might already be able to guess, this has important security implications
|
||||
if you ever attempt to load remote content. You can find more information and
|
||||
guidance on loading remote content in our [security documentation][security].
|
||||
|
||||
2) You can use Node.js modules in your application. Pick your favorite npm
|
||||
module. npm offers currently the world's biggest repository of open-source
|
||||
code – the ability to use well-maintained and tested code that used to be
|
||||
reserved for server applications is one of the key features of Electron.
|
||||
|
||||
As an example, to use the official AWS SDK in your application, you'd first
|
||||
install it as a dependency:
|
||||
|
||||
```sh
|
||||
npm install --save aws-sdk
|
||||
```
|
||||
|
||||
Then, in your Electron app, require and use the module as if you were
|
||||
building a Node.js application:
|
||||
|
||||
```javascript
|
||||
// A ready-to-use S3 Client
|
||||
const S3 = require('aws-sdk/clients/s3')
|
||||
```
|
||||
|
||||
There is one important caveat: Native Node.js modules (that is, modules that
|
||||
require compilation of native code before they can be used) will need to be
|
||||
compiled to be used with Electron.
|
||||
|
||||
The vast majority of Node.js modules are _not_ native. Only 400 out of the
|
||||
~650,000 modules are native. However, if you do need native modules, please
|
||||
consult [this guide on how to recompile them for Electron][native-node].
|
||||
|
||||
[node-docs]: https://nodejs.org/en/docs/
|
||||
[security]: ./security.md
|
||||
[native-node]: ./using-native-node-modules.md
|
||||
[share-data]: ../faq.md#how-to-share-data-between-web-pages
|
||||
|
|
@ -1,223 +0,0 @@
|
|||
# Writing Your First Electron App
|
||||
|
||||
Electron enables you to create desktop applications with pure JavaScript by
|
||||
providing a runtime with rich native (operating system) APIs. You could see it
|
||||
as a variant of the Node.js runtime that is focused on desktop applications
|
||||
instead of web servers.
|
||||
|
||||
This doesn't mean Electron is a JavaScript binding to graphical user interface
|
||||
(GUI) libraries. Instead, Electron uses web pages as its GUI, so you could also
|
||||
see it as a minimal Chromium browser, controlled by JavaScript.
|
||||
|
||||
**Note**: This example is also available as a repository you can
|
||||
[download and run immediately](#trying-this-example).
|
||||
|
||||
As far as development is concerned, an Electron application is essentially a
|
||||
Node.js application. The starting point is a `package.json` that is identical
|
||||
to that of a Node.js module. A most basic Electron app would have the following
|
||||
folder structure:
|
||||
|
||||
```plaintext
|
||||
your-app/
|
||||
├── package.json
|
||||
├── main.js
|
||||
└── index.html
|
||||
```
|
||||
|
||||
Create a new empty folder for your new Electron application. Open up your
|
||||
command line client and run `npm init` from that very folder.
|
||||
|
||||
```sh
|
||||
npm init
|
||||
```
|
||||
|
||||
npm will guide you through creating a basic `package.json` file. The script
|
||||
specified by the `main` field is the startup script of your app, which will
|
||||
run the main process. An example of your `package.json` might look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "your-app",
|
||||
"version": "0.1.0",
|
||||
"main": "main.js"
|
||||
}
|
||||
```
|
||||
|
||||
__Note__: If the `main` field is not present in `package.json`, Electron will
|
||||
attempt to load an `index.js` (as Node.js does).
|
||||
|
||||
By default, `npm start` would run the main script with Node.js. in order to make
|
||||
it run with Electron, you can add a `start` script:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "your-app",
|
||||
"version": "0.1.0",
|
||||
"main": "main.js",
|
||||
"scripts": {
|
||||
"start": "electron ."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Installing Electron
|
||||
|
||||
At this point, you'll need to install `electron` itself. The recommended way
|
||||
of doing so is to install it as a development dependency in your app, which
|
||||
allows you to work on multiple apps with different Electron versions. To do so,
|
||||
run the following command from your app's directory:
|
||||
|
||||
```sh
|
||||
npm install --save-dev electron
|
||||
```
|
||||
|
||||
Other means for installing Electron exist. Please consult the
|
||||
[installation guide](installation.md) to learn about use with proxies, mirrors,
|
||||
and custom caches.
|
||||
|
||||
## Electron Development in a Nutshell
|
||||
|
||||
Electron apps are developed in JavaScript using the same principles and methods
|
||||
found in Node.js development. All APIs and features found in Electron are
|
||||
accessible through the `electron` module, which can be required like any other
|
||||
Node.js module:
|
||||
|
||||
```javascript
|
||||
const electron = require('electron')
|
||||
```
|
||||
|
||||
The `electron` module exposes features in namespaces. As examples, the lifecycle
|
||||
of the application is managed through `electron.app`, windows can be created
|
||||
using the `electron.BrowserWindow` class. A simple `main.js` file might wait
|
||||
for the application to be ready and open a window:
|
||||
|
||||
```javascript
|
||||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
// Create the browser window.
|
||||
const win = new BrowserWindow({
|
||||
width: 800,
|
||||
height: 600,
|
||||
webPreferences: {
|
||||
nodeIntegration: true
|
||||
}
|
||||
})
|
||||
|
||||
// and load the index.html of the app.
|
||||
win.loadFile('index.html')
|
||||
}
|
||||
|
||||
app.whenReady().then(createWindow)
|
||||
```
|
||||
|
||||
The `main.js` should create windows and handle all the system events your
|
||||
application might encounter. A more complete version of the above example
|
||||
might open developer tools, handle the window being closed, or re-create
|
||||
windows on macOS if the user clicks on the app's icon in the dock.
|
||||
|
||||
```javascript
|
||||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
// Create the browser window.
|
||||
const win = new BrowserWindow({
|
||||
width: 800,
|
||||
height: 600,
|
||||
webPreferences: {
|
||||
nodeIntegration: true
|
||||
}
|
||||
})
|
||||
|
||||
// and load the index.html of the app.
|
||||
win.loadFile('index.html')
|
||||
|
||||
// Open the DevTools.
|
||||
win.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)
|
||||
|
||||
// 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()
|
||||
}
|
||||
})
|
||||
|
||||
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()
|
||||
}
|
||||
})
|
||||
|
||||
// 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.
|
||||
```
|
||||
|
||||
Finally the `index.html` is the web page you want to show:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Hello World!</title>
|
||||
<!-- https://electronjs.org/docs/tutorial/security#csp-meta-tag -->
|
||||
<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
|
||||
</head>
|
||||
<body>
|
||||
<h1>Hello World!</h1>
|
||||
We are using node <script>document.write(process.versions.node)</script>,
|
||||
Chrome <script>document.write(process.versions.chrome)</script>,
|
||||
and Electron <script>document.write(process.versions.electron)</script>.
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Running Your App
|
||||
|
||||
Once you've created your initial `main.js`, `index.html`, and `package.json`
|
||||
files, you can try your app by running `npm start` from your application's
|
||||
directory.
|
||||
|
||||
**Note**: If you are building this project without downloading the example
|
||||
repository, your `start` script in `package.json` should look like this
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"start": "electron ."
|
||||
}
|
||||
```
|
||||
|
||||
## Trying this Example
|
||||
|
||||
Clone and run the code in this tutorial by using the
|
||||
[`electron/electron-quick-start`][quick-start] repository.
|
||||
|
||||
**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
|
||||
|
||||
```sh
|
||||
# Clone the repository
|
||||
$ git clone https://github.com/electron/electron-quick-start
|
||||
# Go into the repository
|
||||
$ cd electron-quick-start
|
||||
# Install dependencies
|
||||
$ npm install
|
||||
# Run the app
|
||||
$ npm start
|
||||
```
|
||||
|
||||
For a list of boilerplates and tools to kick-start your development process,
|
||||
see the [Boilerplates and CLIs documentation][boilerplates].
|
||||
|
||||
[share-data]: ../faq.md#how-to-share-data-between-web-pages
|
||||
[quick-start]: https://github.com/electron/electron-quick-start
|
||||
[boilerplates]: ./boilerplates-and-clis.md
|
||||
|
|
@ -1,22 +1,300 @@
|
|||
# Quick Start
|
||||
# Quick Start Guide
|
||||
|
||||
Electron enables you to create desktop applications with pure JavaScript by
|
||||
providing a runtime with rich native (operating system) APIs. You could see it
|
||||
as a variant of the Node.js runtime that is focused on desktop applications
|
||||
instead of web servers.
|
||||
## Quickstart
|
||||
|
||||
The old "Quick Start" document that used to live here has been split up into
|
||||
two documents:
|
||||
Electron is a framework that enables you to create desktop applications with JavaScript, HTML, and CSS. These applications can then be packaged to run directly on macOS, Windows, or Linux, or distributed via the Mac App Store or the Microsoft Store.
|
||||
|
||||
* To check out how a simple Electron app is built, see
|
||||
[Writing Your First Electron App][first-app]
|
||||
* To check out the process architecture, see
|
||||
[Main and Renderer Processes][processes].
|
||||
Typically, you create a desktop application for an operating system (OS) using each operating system's specific native application frameworks. Electron makes it possible to write your application once using technologies that you already know.
|
||||
|
||||
To learn more about Electron, check out the
|
||||
[official guides][readme].
|
||||
### Prerequisites
|
||||
|
||||
[first-app]: ./first-app.md
|
||||
[processes]: ./application-architecture.md#main-and-renderer-processes
|
||||
[readme]: ../
|
||||
Before proceeding with Electron you need to install [Node.js][node-download].
|
||||
We recommend that you install either the latest `LTS` or `Current` 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.
|
||||
If both commands succeeded, you are ready to install Electron.
|
||||
|
||||
### Create a basic application
|
||||
|
||||
From a development perspective, an Electron application is essentially a Node.js application. This means that the starting point of your Electron application will be a `package.json` file like in any other Node.js application. A minimal Electron application has the following structure:
|
||||
|
||||
```plain
|
||||
my-electron-app/
|
||||
├── package.json
|
||||
├── main.js
|
||||
└── index.html
|
||||
```
|
||||
|
||||
Let's create a basic application based on the structure above.
|
||||
|
||||
#### Install Electron
|
||||
|
||||
Create a folder for your project and install Electron there:
|
||||
|
||||
```sh
|
||||
mkdir my-electron-app && cd my-electron-app
|
||||
npm init -y
|
||||
npm i --save-dev electron
|
||||
```
|
||||
|
||||
#### Create the main script file
|
||||
|
||||
The main script specifies the entry point of your Electron application (in our case, the `main.js` file) that will run the Main process. Typically, the script that runs in the Main process controls the lifecycle of the application, displays the graphical user interface and its elements, performs native operating system interactions, and creates Renderer processes within web pages. An Electron application can have only one Main process.
|
||||
|
||||
The main script may look as follows:
|
||||
|
||||
```js
|
||||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({
|
||||
width: 800,
|
||||
height: 600,
|
||||
webPreferences: {
|
||||
nodeIntegration: true
|
||||
}
|
||||
})
|
||||
|
||||
win.loadFile('index.html')
|
||||
win.webContents.openDevTools()
|
||||
}
|
||||
|
||||
app.whenReady().then(createWindow)
|
||||
|
||||
app.on('window-all-closed', () => {
|
||||
if (process.platform !== 'darwin') {
|
||||
app.quit()
|
||||
}
|
||||
})
|
||||
|
||||
app.on('activate', () => {
|
||||
if (BrowserWindow.getAllWindows().length === 0) {
|
||||
createWindow()
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
##### What is going on above?
|
||||
|
||||
1. Line 1: First, you import the `app` and `BrowserWindow` modules of the `electron` package to be able to manage your application's lifecycle events, as well as create and control browser windows.
|
||||
2. Line 3: After that, you define a function that creates a [new browser window](../api/browser-window.md#new-browserwindowoptions) with node integration enabled, loads `index.html` file into this window (line 12, we will discuss the file later) and opens Developer Tools (line 13).
|
||||
3. Line 16: You create a new browser window by invoking the `createWindow` function once the Electron application [is initialized](../api/app.md#appwhenready).
|
||||
4. Line 18: You add a new listener that tries to quit the application when it no longer has any open windows. This listener is a no-op on macOS due to the operating system's [window management behavior](https://support.apple.com/en-ca/guide/mac-help/mchlp2469/mac).
|
||||
5. Line 24: You add a new listener that creates a new browser window only if when the application has no visible windows after being activated. For example, after launching the application for the first time, or re-launching the already running application.
|
||||
|
||||
#### Create a web page
|
||||
|
||||
This is the web page you want to display once the application is initialized. This web page represents the Renderer process. You can create multiple browser windows, where each window uses its own independent Renderer. Each window can optionally be granted with full access to Node.js API through the `nodeIntegration` preference.
|
||||
|
||||
The `index.html` page looks as follows:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Hello World!</title>
|
||||
<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
|
||||
</head>
|
||||
<body>
|
||||
<h1>Hello World!</h1>
|
||||
We are using node <script>document.write(process.versions.node)</script>,
|
||||
Chrome <script>document.write(process.versions.chrome)</script>,
|
||||
and Electron <script>document.write(process.versions.electron)</script>.
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
#### Modify your package.json file
|
||||
|
||||
Your Electron application uses the `package.json` file as the main entry point (as any other Node.js application). The main script of your application is `main.js`, so modify the `package.json` file accordingly:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-electron-app",
|
||||
"version": "0.1.0",
|
||||
"main": "main.js"
|
||||
}
|
||||
```
|
||||
|
||||
> NOTE: If the `main` field is omitted, Electron will attempt to load an `index.js` file from the directory containing `package.json`.
|
||||
|
||||
By default, the `npm start` command will run the main script with Node.js. To run the script with Electron, you need to change it as such:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-electron-app",
|
||||
"version": "0.1.0",
|
||||
"main": "main.js",
|
||||
"scripts": {
|
||||
"start": "electron ."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Run your application
|
||||
|
||||
```sh
|
||||
npm start
|
||||
```
|
||||
|
||||
Your running Electron app should look as follows:
|
||||
|
||||
|
||||
|
||||
### Package and distribute the application
|
||||
|
||||
The simplest and the fastest way to distribute your newly created app is using
|
||||
[Electron Forge](https://www.electronforge.io).
|
||||
|
||||
1. Import Electron Forge to your app folder:
|
||||
|
||||
```sh
|
||||
npx @electron-forge/cli 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"!!!
|
||||
```
|
||||
|
||||
1. Create a distributable:
|
||||
|
||||
```sh
|
||||
npm run make
|
||||
|
||||
> my-gsod-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
|
||||
```
|
||||
|
||||
[node-download]: https://nodejs.org/en/download/
|
||||
|
||||
## Learning the basics
|
||||
|
||||
This section guides you through the basics of how Electron works under the hood. It aims at strengthening knowledge about Electron and the application created earlier in the Quickstart section.
|
||||
|
||||
### Application architecture
|
||||
|
||||
Electron consists of three main pillars:
|
||||
|
||||
* **Chromium** for displaying web content.
|
||||
* **Node.js** for working with the local filesystem and the operating system.
|
||||
* **Custom APIs** for working with often-needed OS native functions.
|
||||
|
||||
Developing an application with Electron is like building a Node.js app with a web interface or building web pages with seamless Node.js integration.
|
||||
|
||||
#### Main and Renderer Processes
|
||||
|
||||
As it was mentioned before, Electron has two types of processes: Main and Renderer.
|
||||
|
||||
* The Main process **creates** web pages by creating `BrowserWindow` instances. Each `BrowserWindow` instance runs the web page in its Renderer process. When a `BrowserWindow` instance is destroyed, the corresponding Renderer process gets terminated as well.
|
||||
* The Main process **manages** all web pages and their corresponding Renderer processes.
|
||||
|
||||
----
|
||||
|
||||
* The Renderer process **manages** only the corresponding web page. A crash in one Renderer process does not affect other Renderer processes.
|
||||
* The Renderer process **communicates** with the Main process via IPC to perform GUI operations in a web page. Calling native GUI-related APIs from the Renderer process directly is restricted due to security concerns and potential resource leakage.
|
||||
|
||||
----
|
||||
|
||||
The communication between processes is possible via Inter-Process Communication (IPC) modules: [`ipcMain`](../api/ipc-main.md) and [`ipcRenderer`](../api/ipc-renderer.md).
|
||||
|
||||
#### APIs
|
||||
|
||||
##### Electron API
|
||||
|
||||
Electron APIs are assigned based on the process type, meaning that some modules can be used from either the Main or Renderer process, and some from both. Electron's API documentation indicates which process each module can be used from.
|
||||
|
||||
For example, to access the Electron API in both processes, require its included module:
|
||||
|
||||
```js
|
||||
const electron = require('electron')
|
||||
```
|
||||
|
||||
To create a window, call the `BrowserWindow` class, which is only available in the Main process:
|
||||
|
||||
```js
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow()
|
||||
```
|
||||
|
||||
To call the Main process from the Renderer, use the IPC module:
|
||||
|
||||
```js
|
||||
// In the Main process
|
||||
const { ipcMain } = require('electron')
|
||||
|
||||
ipcMain.handle('perform-action', (event, ...args) => {
|
||||
// ... do actions on behalf of the Renderer
|
||||
})
|
||||
```
|
||||
|
||||
```js
|
||||
// In the Renderer process
|
||||
const { ipcRenderer } = require('electron')
|
||||
|
||||
ipcRenderer.invoke('perform-action', ...args)
|
||||
```
|
||||
|
||||
> NOTE: Because Renderer processes may run untrusted code (especially from third parties), it is important to carefully validate the requests that come to the Main process.
|
||||
|
||||
##### Node.js API
|
||||
|
||||
> NOTE: To access the Node.js API from the Renderer process, you need to set the `nodeIntegration` preference to `true`.
|
||||
|
||||
Electron exposes full access to Node.js API and its modules both in the Main and the Renderer processes. For example, you can read all the files from the root directory:
|
||||
|
||||
```js
|
||||
const fs = require('fs')
|
||||
|
||||
const root = fs.readdirSync('/')
|
||||
|
||||
console.log(root)
|
||||
```
|
||||
|
||||
To use a Node.js module, you first need to install it as a dependency:
|
||||
|
||||
```sh
|
||||
npm install --save aws-sdk
|
||||
```
|
||||
|
||||
Then, in your Electron application, require the module:
|
||||
|
||||
```js
|
||||
const S3 = require('aws-sdk/clients/s3')
|
||||
```
|
||||
|
|
@ -7,7 +7,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.
|
||||
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](first-app.md), 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](quick-start.md#prerequisites), npm will download and unpack the arm64 version. You can then package and distribute your app as normal.
|
||||
|
||||
## General considerations
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue