2015-09-01 02:18:46 +00:00
# Quick Start
2013-09-09 07:35:57 +00:00
2015-09-01 02:18:46 +00:00
Electron enables you to create desktop applications with pure JavaScript by
providing a runtime with rich native (operating system) APIs. You could see it
2015-10-05 18:12:29 +00:00
as a variant of the Node.js runtime that is focused on desktop applications
2015-09-01 02:18:46 +00:00
instead of web servers.
2013-08-14 22:43:35 +00:00
2015-09-01 02:18:46 +00:00
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.
2013-08-14 22:43:35 +00:00
2015-09-01 02:18:46 +00:00
### Main Process
2013-08-14 22:43:35 +00:00
2015-04-24 00:12:04 +00:00
In Electron, the process that runs `package.json` 's `main` script is called
2015-09-01 02:18:46 +00:00
__the main process__. The script that runs in the main process can display a GUI
by creating web pages.
2014-04-30 08:39:49 +00:00
2015-09-01 02:18:46 +00:00
### Renderer Process
2014-04-30 08:39:49 +00:00
2015-04-19 15:46:00 +00:00
Since Electron uses Chromium for displaying web pages, Chromium's
2015-07-14 20:28:57 +00:00
multi-process architecture is also used. Each web page in Electron runs in
2015-03-29 08:02:03 +00:00
its own process, which is called __the renderer process__ .
2015-07-14 20:28:57 +00:00
In normal browsers, web pages usually run in a sandboxed environment and are not
2015-10-05 18:12:29 +00:00
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.
2015-03-29 08:02:03 +00:00
2015-09-01 02:18:46 +00:00
### Differences Between Main Process and Renderer Process
2014-04-30 08:39:49 +00:00
2015-09-01 02:18:46 +00:00
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
2015-07-14 20:28:57 +00:00
is also terminated.
2014-04-30 08:39:49 +00:00
2015-04-24 00:12:04 +00:00
The main process manages all web pages and their corresponding renderer
2016-02-16 03:52:47 +00:00
processes. Each renderer process is isolated and only cares about the web page
running in it.
2015-03-29 08:02:03 +00:00
2015-09-01 02:18:46 +00:00
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.
2015-03-29 08:02:03 +00:00
2016-02-16 03:52:47 +00:00
In Electron, we have several ways to communicate between the main process and
renderer processes. Like [`ipcRenderer` ](../api/ipc-renderer.md ) and
[`ipcMain` ](../api/ipc-main.md ) modules for sending messages, and the
[remote ](../api/remote.md ) module for RPC style communication. There is also
2016-07-12 17:59:29 +00:00
an FAQ entry on [how to share data between web pages][share-data].
2016-02-06 18:57:21 +00:00
2015-09-01 02:18:46 +00:00
## Write your First Electron App
2013-08-14 22:43:35 +00:00
2015-09-01 02:18:46 +00:00
Generally, an Electron app is structured like this:
2013-08-14 22:43:35 +00:00
```text
2014-05-07 19:21:13 +00:00
your-app/
2013-08-14 22:43:35 +00:00
├── package.json
├── main.js
└── index.html
```
2014-09-25 15:22:29 +00:00
The format of `package.json` is exactly the same as that of Node's modules, and
the script specified by the `main` field is the startup script of your app,
2015-09-01 02:18:46 +00:00
which will run the main process. An example of your `package.json` might look
2014-09-25 15:22:29 +00:00
like this:
2013-08-14 22:43:35 +00:00
```json
{
2014-04-30 09:28:36 +00:00
"name" : "your-app",
2013-08-14 22:43:35 +00:00
"version" : "0.1.0",
"main" : "main.js"
}
```
2015-08-24 13:14:38 +00:00
__Note__: If the `main` field is not present in `package.json` , Electron will
attempt to load an `index.js` .
2014-07-21 14:02:35 +00:00
The `main.js` should create windows and handle system events, a typical
example being:
2013-08-14 22:43:35 +00:00
```javascript
2016-05-10 16:57:55 +00:00
const electron = require('electron');
2016-04-29 20:17:50 +00:00
// Module to control application life.
2016-05-10 17:15:09 +00:00
const {app} = electron;
2016-04-29 20:17:50 +00:00
// Module to create native browser window.
2016-05-10 17:15:09 +00:00
const {BrowserWindow} = electron;
2014-04-30 09:28:36 +00:00
2013-08-14 22:43:35 +00:00
// Keep a global reference of the window object, if you don't, the window will
2015-09-01 02:18:46 +00:00
// be closed automatically when the JavaScript object is garbage collected.
2016-05-10 17:38:42 +00:00
let win;
2013-08-14 22:43:35 +00:00
2016-05-10 17:15:09 +00:00
function createWindow() {
2014-04-30 09:28:36 +00:00
// Create the browser window.
2016-05-10 17:38:42 +00:00
win = new BrowserWindow({width: 800, height: 600});
2014-04-30 09:28:36 +00:00
2013-08-14 22:43:35 +00:00
// and load the index.html of the app.
2016-05-10 17:38:42 +00:00
win.loadURL(`file://${__dirname}/index.html`);
2013-08-14 22:43:35 +00:00
2015-09-01 02:18:46 +00:00
// Open the DevTools.
2016-05-10 17:38:42 +00:00
win.webContents.openDevTools();
2015-05-21 03:16:39 +00:00
2014-04-30 09:28:36 +00:00
// Emitted when the window is closed.
2016-05-10 17:38:42 +00:00
win.on('closed', () => {
2013-08-14 22:43:35 +00:00
// Dereference the window object, usually you would store windows
// in an array if your app supports multi windows, this is the time
// when you should delete the corresponding element.
2016-05-10 17:38:42 +00:00
win = null;
2016-05-04 18:11:51 +00:00
});
2016-04-29 20:17:50 +00:00
}
// 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.
2016-05-04 18:11:51 +00:00
app.on('ready', createWindow);
2016-04-29 20:17:50 +00:00
// Quit when all windows are closed.
2016-05-04 18:11:51 +00:00
app.on('window-all-closed', () => {
2016-06-18 13:26:26 +00:00
// On macOS it is common for applications and their menu bar
2016-04-29 20:17:50 +00:00
// to stay active until the user quits explicitly with Cmd + Q
if (process.platform !== 'darwin') {
2016-05-04 18:11:51 +00:00
app.quit();
2016-04-29 20:17:50 +00:00
}
2016-05-04 18:11:51 +00:00
});
2016-04-29 20:17:50 +00:00
2016-05-04 18:11:51 +00:00
app.on('activate', () => {
2016-06-18 13:26:26 +00:00
// On macOS it's common to re-create a window in the app when the
2016-04-29 20:17:50 +00:00
// dock icon is clicked and there are no other windows open.
2016-05-10 17:38:42 +00:00
if (win === null) {
2016-05-04 18:11:51 +00:00
createWindow();
2016-04-29 20:17:50 +00:00
}
2016-05-04 18:11:51 +00:00
});
2016-04-29 20:17:50 +00:00
// 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.
2013-08-14 22:43:35 +00:00
```
2014-04-30 09:28:36 +00:00
Finally the `index.html` is the web page you want to show:
```html
<!DOCTYPE html>
< html >
< head >
2015-09-23 08:21:03 +00:00
< meta charset = "UTF-8" >
2014-04-30 09:28:36 +00:00
< title > Hello World!< / title >
< / head >
< body >
< h1 > Hello World!< / h1 >
2015-10-19 23:37:18 +00:00
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 > .
2014-04-30 09:28:36 +00:00
< / body >
< / html >
```
## Run your app
2015-07-27 00:26:10 +00:00
Once you've created your initial `main.js` , `index.html` , and `package.json` files,
you'll probably want to try running your app locally to test it and make sure it's
working as expected.
### electron-prebuilt
2015-09-01 02:18:46 +00:00
2016-04-29 20:32:00 +00:00
[`electron-prebuilt` ](https://github.com/electron-userland/electron-prebuilt ) is
an `npm` module that contains pre-compiled versions of Electron.
If you've installed it globally with `npm` , then you will only need to run the
following in your app's source directory:
2015-07-27 00:26:10 +00:00
```bash
electron .
```
If you've installed it locally, then run:
2014-04-30 09:28:36 +00:00
2015-07-27 00:26:10 +00:00
```bash
./node_modules/.bin/electron .
```
### Manually Downloaded Electron Binary
2015-09-01 02:18:46 +00:00
2015-09-29 03:09:13 +00:00
If you downloaded Electron manually, you can also use the included
2015-07-27 00:26:10 +00:00
binary to execute your app directly.
#### Windows
2014-04-30 09:28:36 +00:00
2015-05-27 19:51:19 +00:00
```bash
2015-04-20 11:40:04 +00:00
$ .\electron\electron.exe your-app\
2014-04-30 09:28:36 +00:00
```
2015-07-27 00:26:10 +00:00
#### Linux
2014-04-30 09:28:36 +00:00
```bash
2015-04-20 11:40:04 +00:00
$ ./electron/electron your-app/
2014-04-30 09:28:36 +00:00
```
2016-06-18 13:26:26 +00:00
#### macOS
2014-04-30 09:28:36 +00:00
```bash
2015-04-22 14:22:08 +00:00
$ ./Electron.app/Contents/MacOS/Electron your-app/
2014-04-30 09:28:36 +00:00
```
2014-07-01 09:49:08 +00:00
2015-04-19 15:46:00 +00:00
`Electron.app` here is part of the Electron's release package, you can download
2016-03-31 23:49:59 +00:00
it from [here ](https://github.com/electron/electron/releases ).
2015-07-27 00:26:10 +00:00
### Run as a distribution
2015-09-01 02:18:46 +00:00
2015-07-27 00:26:10 +00:00
After you're done writing your app, you can create a distribution by
2015-09-01 02:18:46 +00:00
following the [Application Distribution ](./application-distribution.md ) guide
2015-07-27 00:31:01 +00:00
and then executing the packaged app.
2015-10-19 22:52:02 +00:00
### Try this Example
2016-06-24 05:59:55 +00:00
Clone and run the code in this tutorial by using the [`electron/electron-quick-start` ](https://github.com/electron/electron-quick-start )
2015-10-19 22:52:02 +00:00
repository.
**Note**: Running this requires [Git ](https://git-scm.com ) and [Node.js ](https://nodejs.org/en/download/ ) (which includes [npm ](https://npmjs.org )) on your system.
```bash
# Clone the repository
2016-03-31 23:49:59 +00:00
$ git clone https://github.com/electron/electron-quick-start
2015-10-19 22:52:02 +00:00
# Go into the repository
$ cd electron-quick-start
# Install dependencies and run the app
$ npm install & & npm start
```
2016-02-16 03:52:47 +00:00
2016-07-12 17:59:29 +00:00
[share-data]: ../faq.md#how-to-share-data-between-web-pages