2013-09-09 07:35:57 +00:00
# Quick start
2013-08-14 22:43:35 +00:00
## Introduction
2015-04-24 00:12:04 +00:00
Electron enables you to create desktop applications with pure JavaScript by providing a runtime with rich native APIs. You could see it as a variant of the io.js runtime which is focused on desktop applications instead of web servers.
2013-08-14 22:43:35 +00:00
2015-04-19 15:46:00 +00:00
It doesn't mean Electron is a JavaScript binding to GUI libraries. Instead,
Electron uses web pages as its GUI, so you could also see it as a minimal
2014-09-25 15:22:29 +00:00
Chromium browser, controlled by JavaScript.
2013-08-14 22:43:35 +00:00
2015-04-24 00:12:04 +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
__the main process__. The script that runs in the main process, can display GUI by
2015-03-29 08:02:03 +00:00
creating web pages.
2014-04-30 08:39:49 +00:00
2015-04-24 00:12:04 +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
multi-processes 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-04-15 17:58:30 +00:00
In normal browsers web pages usually run in a sandboxed environment and are not
2015-04-24 00:12:04 +00:00
allowed access to native resources. Electron users however, have the power to use
io.js APIs in web pages allowing lower level operating system interactions.
2015-03-29 08:02:03 +00:00
### Differences between main process and renderer process
2014-04-30 08:39:49 +00:00
2015-04-24 00:12:04 +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-03-29 08:02:03 +00:00
would also be 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
processes, each renderer process is isolated and only cares
2015-03-29 08:02:03 +00:00
about the web page running in it.
2015-04-05 20:18:20 +00:00
In web pages, it is not allowed to call native GUI related APIs because managing
2015-03-29 08:02:03 +00:00
native GUI resources in web pages is very dangerous and easy to leak resources.
If you want to do GUI operations in web pages, you have to communicate with
the main process to do it there.
2015-04-19 15:46:00 +00:00
In Electron, we have provided the [ipc ](../api/ipc-renderer.md ) module for
2015-03-29 08:02:03 +00:00
communication between main process and renderer process. And there is also a
[remote ](../api/remote.md ) module for RPC style communication.
2014-04-30 08:39:49 +00:00
2015-04-19 15:46:00 +00:00
## Write your first Electron app
2013-08-14 22:43:35 +00:00
2015-04-20 11:40:04 +00:00
Generally, an Electron app would be 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-03-26 15:20:31 +00:00
which will run on 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"
}
```
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
var app = require('app'); // Module to control application life.
2014-04-30 09:28:36 +00:00
var BrowserWindow = require('browser-window'); // Module to create native browser window.
// Report crashes to our server.
require('crash-reporter').start();
2013-08-14 22:43:35 +00:00
// Keep a global reference of the window object, if you don't, the window will
// be closed automatically when the javascript object is GCed.
var mainWindow = null;
// Quit when all windows are closed.
app.on('window-all-closed', function() {
2015-06-09 16:17:12 +00:00
if (process.platform != 'darwin') {
2014-04-30 09:28:36 +00:00
app.quit();
2015-06-09 16:17:12 +00:00
}
2013-08-14 22:43:35 +00:00
});
2015-04-19 15:46:00 +00:00
// This method will be called when Electron has done everything
2013-08-14 22:43:35 +00:00
// initialization and ready for creating browser windows.
2013-12-27 03:08:26 +00:00
app.on('ready', function() {
2014-04-30 09:28:36 +00:00
// Create the browser window.
mainWindow = new BrowserWindow({width: 800, height: 600});
2013-08-14 22:43:35 +00:00
// and load the index.html of the app.
mainWindow.loadUrl('file://' + __dirname + '/index.html');
2015-05-21 03:16:39 +00:00
// Open the devtools.
mainWindow.openDevTools();
2014-04-30 09:28:36 +00:00
// Emitted when the window is closed.
2013-08-14 22:43:35 +00:00
mainWindow.on('closed', function() {
// 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.
mainWindow = null;
});
2013-12-17 14:08:45 +00:00
});
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 >
< title > Hello World!< / title >
< / head >
< body >
< h1 > Hello World!< / h1 >
2015-04-22 20:14:50 +00:00
We are using io.js < script > document . write ( process . version ) < / script >
2015-04-19 15:46:00 +00:00
and Electron < script > document . write ( process . versions [ 'electron' ] ) < / script > .
2014-04-30 09:28:36 +00:00
< / body >
< / html >
```
## Run your app
2014-07-21 14:02:35 +00:00
After you're done writing your app, you can create a distribution by
2014-05-04 10:32:12 +00:00
following the [Application distribution ](./application-distribution.md ) guide
2014-09-25 15:22:29 +00:00
and then execute the packaged app. You can also just use the downloaded
2015-04-19 15:46:00 +00:00
Electron binary to execute your app directly.
2014-04-30 09:28:36 +00:00
2014-05-07 05:06:35 +00:00
On 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
```
On Linux:
```bash
2015-04-20 11:40:04 +00:00
$ ./electron/electron your-app/
2014-04-30 09:28:36 +00:00
```
2015-02-02 08:21:23 +00:00
On OS X:
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
2015-04-16 03:31:12 +00:00
it from [here ](https://github.com/atom/electron/releases ).
