electron/docs/tutorial/quick-start.md

# Quick start

## Introduction

Generally, 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.

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
Chromium browser, controlled by JavaScript.

### The main process

In Electron the process that runs `package.json`'s `main` script is called
__the main process__. The script runs in the main process can display GUI by
creating web pages.

### The renderer process

Since Electron uses Chromium for displaying web pages, Chromium's
multi-processes 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. In Electron users have the power to use
io.js APIs in web pages and it is therefore possible to interact with low level
operating system features.

### Differences between main process and renderer process

The main process creates web pages by creating `BrowserWindow` instances, and
each `BrowserWindow` instance runs the web page in its own renderer process,
when a `BrowserWindow` instance is destroyed, the corresponding renderer process
would also be terminated.

So the main process manages all web pages and their corresponding renderer
processes, and each renderer process is separated from each other and only care
about the web page running in it.

In web pages, it is not allowed to call native GUI related APIs because managing
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.

In Electron, we have provided the [ipc](../api/ipc-renderer.md) module for
communication between main process and renderer process. And there is also a
[remote](../api/remote.md) module for RPC style communication.

## Write your first Electron app

Generally, an Electron app would be structured like this:

```text
your-app/
├── package.json
├── main.js
└── index.html
```

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,
which will run on the main process. An example of your `package.json` might look
like this:

```json
{
  "name"    : "your-app",
  "version" : "0.1.0",
  "main"    : "main.js"
}
```

The `main.js` should create windows and handle system events, a typical
example being:

```javascript
var app = require('app');  // Module to control application life.
var BrowserWindow = require('browser-window');  // Module to create native browser window.

// Report crashes to our server.
require('crash-reporter').start();

// 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() {
  if (process.platform != 'darwin')
    app.quit();
});

// This method will be called when Electron has done everything
// initialization and ready for creating browser windows.
app.on('ready', function() {
  // Create the browser window.
  mainWindow = new BrowserWindow({width: 800, height: 600});

  // and load the index.html of the app.
  mainWindow.loadUrl('file://' + __dirname + '/index.html');

  // Emitted when the window is closed.
  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;
  });
});
```

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>
    We are using io.js <script>document.write(process.version)</script>
    and Electron <script>document.write(process.versions['electron'])</script>.
  </body>
</html>
```

## Run your app

After you're done writing your app, you can create a distribution by
following the [Application distribution](./application-distribution.md) guide
and then execute the packaged app. You can also just use the downloaded
Electron binary to execute your app directly.

On Windows:

```cmd
$ .\electron\electron.exe your-app\
```

On Linux:

```bash
$ ./electron/electron your-app/
```

On OS X:

```bash
$ ./Electron.app/Contents/MacOS/Electron your-app/
```

`Electron.app` here is part of the Electron's release package, you can download
it from [here](https://github.com/atom/electron/releases).
doc: Add titles for all pages. 2013-09-09 11:35:57 +04:00			`# Quick start`

Move wiki content to docs dir 2013-08-15 02:43:35 +04:00			`## Introduction`

docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`Generally, Electron enables you to create desktop applications with pure`
Capitilization, grammar, and punctuation changes 2014-05-07 09:06:35 +04:00			`JavaScript by providing a runtime with rich native APIs. You could see it as`
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03:00			`a variant of the io.js runtime which is focused on desktop applications`
Ironed out some spelling and grammar issues. 2014-07-21 18:02:35 +04:00			`instead of web servers.`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00
docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03: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`
Make docs follow 80 columns rule. 2014-09-25 19:22:29 +04:00			`Chromium browser, controlled by JavaScript.`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00
Renamed browser-side to main process renamed a few occurances of "web page" to "renderer" renamed a few files that had "browser" in their name to "main-process" note that there are still many occurances of web page. 2015-03-26 18:20:31 +03:00			`### The main process`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00
docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			In Electron the process that runs `package.json`'s `main` script is called
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03:00			`__the main process__. The script runs in the main process can display GUI by`
			`creating web pages.`
:memo: Simpler introduction in quick start. 2014-04-30 12:39:49 +04:00
Renamed browser-side to main process renamed a few occurances of "web page" to "renderer" renamed a few files that had "browser" in their name to "main-process" note that there are still many occurances of web page. 2015-03-26 18:20:31 +03:00			`### The renderer process`
:memo: Simpler introduction in quick start. 2014-04-30 12:39:49 +04:00
docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`Since Electron uses Chromium for displaying web pages, Chromium's`
			`multi-processes architecture is also used. Each web page in Electron runs in`
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03:00			`its own process, which is called __the renderer process__.`

fixes spelling typo 2015-04-15 20:58:30 +03:00			`In normal browsers web pages usually run in a sandboxed environment and are not`
Merge branch 'master' of https://github.com/NKMR6194/electron into NKMR6194-master 2015-04-20 14:40:04 +03:00			`allowed access to native resources. In Electron users have the power to use`
removes use of passive voice 2015-04-15 21:01:09 +03:00			`io.js APIs in web pages and it is therefore possible to interact with low level`
			`operating system features.`
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03:00
			`### Differences between main process and renderer process`
:memo: Simpler introduction in quick start. 2014-04-30 12:39:49 +04:00
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03:00			The main process creates web pages by creating `BrowserWindow` instances, and
			each `BrowserWindow` instance runs the web page in its own renderer process,
			when a `BrowserWindow` instance is destroyed, the corresponding renderer process
			`would also be terminated.`
:memo: Simpler introduction in quick start. 2014-04-30 12:39:49 +04:00
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03:00			`So the main process manages all web pages and their corresponding renderer`
			`processes, and each renderer process is separated from each other and only care`
			`about the web page running in it.`

add `to` in sentence for grammar Simply a small grammar improvement. 2015-04-05 23:18:20 +03:00			`In web pages, it is not allowed to call native GUI related APIs because managing`
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03: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.`

docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`In Electron, we have provided the [ipc](../api/ipc-renderer.md) module for`
docs: Say more about what is renderer process and main process 2015-03-29 11:02:03 +03:00			`communication between main process and renderer process. And there is also a`
			`[remote](../api/remote.md) module for RPC style communication.`
:memo: Simpler introduction in quick start. 2014-04-30 12:39:49 +04:00
docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`## Write your first Electron app`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00
Merge branch 'master' of https://github.com/NKMR6194/electron into NKMR6194-master 2015-04-20 14:40:04 +03:00			`Generally, an Electron app would be structured like this:`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00
			```text
Update "app" to "your-app" to avoid module collision with require('app') If you name your app's folder `app/` and if you run the atom-shell from the directory above that, it will result in an error, which I believe is caused by resolving `require('app')` to your `app/` folder. So just to avoid confusion where someone might create an app with that folder and run the atom-shell from that directory. I wrote up some details getting atom-shell working using the grunt plugin. - https://github.com/atom/atom-shell/issues/256#issuecomment-42464026 2014-05-07 23:21:13 +04:00			`your-app/`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00			`├── package.json`
			`├── main.js`
			`└── index.html`
			```

Make docs follow 80 columns rule. 2014-09-25 19:22:29 +04: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,
Renamed browser-side to main process renamed a few occurances of "web page" to "renderer" renamed a few files that had "browser" in their name to "main-process" note that there are still many occurances of web page. 2015-03-26 18:20:31 +03:00			which will run on the main process. An example of your `package.json` might look
Make docs follow 80 columns rule. 2014-09-25 19:22:29 +04:00			`like this:`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00
			```json
			`{`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			`"name" : "your-app",`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00			`"version" : "0.1.0",`
			`"main" : "main.js"`
			`}`
			```

Ironed out some spelling and grammar issues. 2014-07-21 18:02:35 +04:00			The `main.js` should create windows and handle system events, a typical
			`example being:`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00
			```javascript
			`var app = require('app'); // Module to control application life.`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			`var BrowserWindow = require('browser-window'); // Module to create native browser window.`

			`// Report crashes to our server.`
			`require('crash-reporter').start();`
Move wiki content to docs dir 2013-08-15 02:43:35 +04: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() {`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			`if (process.platform != 'darwin')`
			`app.quit();`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00			`});`

docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`// This method will be called when Electron has done everything`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00			`// initialization and ready for creating browser windows.`
Rename 'finish-launching' event to 'ready', 'finish-launching' is more like a OS X message name, and in atom-shell it means initialization has done, so 'ready' seems to be a better name and more easy to remember. The 'will-finish-launching' event just represents the corresponding message on OS X and is the same with 'ready' on other platforms, so we keep its name to indicate that it's only useful for OS X specified code. 2013-12-27 07:08:26 +04:00			`app.on('ready', function() {`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			`// Create the browser window.`
			`mainWindow = new BrowserWindow({width: 800, height: 600});`

Move wiki content to docs dir 2013-08-15 02:43:35 +04:00			`// and load the index.html of the app.`
			`mainWindow.loadUrl('file://' + __dirname + '/index.html');`

:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			`// Emitted when the window is closed.`
Move wiki content to docs dir 2013-08-15 02:43:35 +04: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;`
			`});`
Discard the require('atom-delegate') API. 2013-12-17 18:08:45 +04:00			`});`
Move wiki content to docs dir 2013-08-15 02:43:35 +04:00			```

:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04: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>`
Update quick-start.md 2015-04-22 23:14:50 +03:00			`We are using io.js <script>document.write(process.version)</script>`
docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`and Electron <script>document.write(process.versions['electron'])</script>.`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			`</body>`
			`</html>`
			```

			`## Run your app`

Ironed out some spelling and grammar issues. 2014-07-21 18:02:35 +04:00			`After you're done writing your app, you can create a distribution by`
:memo: Separate the application distribution chapter out. 2014-05-04 14:32:12 +04:00			`following the [Application distribution](./application-distribution.md) guide`
Make docs follow 80 columns rule. 2014-09-25 19:22:29 +04:00			`and then execute the packaged app. You can also just use the downloaded`
docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`Electron binary to execute your app directly.`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00
Capitilization, grammar, and punctuation changes 2014-05-07 09:06:35 +04:00			`On Windows:`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00
			```cmd
Merge branch 'master' of https://github.com/NKMR6194/electron into NKMR6194-master 2015-04-20 14:40:04 +03:00			`$ .\electron\electron.exe your-app\`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			```

			`On Linux:`

			```bash
Merge branch 'master' of https://github.com/NKMR6194/electron into NKMR6194-master 2015-04-20 14:40:04 +03:00			`$ ./electron/electron your-app/`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			```

Change Mac OS X to OS X. Apple has renamed Mac OS X to OS X. 2015-02-02 11:21:23 +03:00			`On OS X:`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00
			```bash
updated bash path to ./Electron.app/Contents/MacOS/Electron it had the trailing /Atom which no longer exists 2015-04-22 17:22:08 +03:00			`$ ./Electron.app/Contents/MacOS/Electron your-app/`
:memo: Update the quick start on writing the app. 2014-04-30 13:28:36 +04:00			```
Add notice for ##Run your app 2014-07-01 13:49:08 +04:00
docs: Atom Shell => Electron in quick-start.md 2015-04-19 18:46:00 +03:00			`Electron.app` here is part of the Electron's release package, you can download
docs: Atom Shell => Electron 2015-04-16 06:31:12 +03:00			`it from [here](https://github.com/atom/electron/releases).`