electron/docs/api/synopsis.md

# Synopsis

> How to use Node.js and Electron APIs.

All of [Node.js's built-in modules](https://nodejs.org/api/) are available in
Electron and third-party node modules also fully supported as well (including
the [native modules](../tutorial/using-native-node-modules.md)).

Electron also provides some extra built-in modules for developing native
desktop applications. Some modules are only available in the main process, some
are only available in the renderer process (web page), and some can be used in
both processes.

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)
scripts to be able to use those modules.

The main process script is like a normal Node.js script:

```javascript
const { app, BrowserWindow } = require('electron')
let win = null

app.whenReady().then(() => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.loadURL('https://github.com')
})
```

The renderer process is no different than a normal web page, except for the
extra ability to use node modules:

```html
<!DOCTYPE html>
<html>
<body>
<script>
  const { app } = require('electron').remote
  console.log(app.getVersion())
</script>
</body>
</html>
```

To run your app, read [Run your app](../tutorial/first-app.md#running-your-app).

## Destructuring assignment

As of 0.37, you can use
[destructuring assignment][destructuring-assignment] to make it easier to use
built-in modules.

```javascript
const { app, BrowserWindow } = require('electron')

let win

app.whenReady().then(() => {
  win = new BrowserWindow()
  win.loadURL('https://github.com')
})
```

If you need the entire `electron` module, you can require it and then using
destructuring to access the individual modules from `electron`.

```javascript
const electron = require('electron')
const { app, BrowserWindow } = electron

let win

app.whenReady().then(() => {
  win = new BrowserWindow()
  win.loadURL('https://github.com')
})
```

This is equivalent to the following code:

```javascript
const electron = require('electron')
const app = electron.app
const BrowserWindow = electron.BrowserWindow
let win

app.whenReady().then(() => {
  win = new BrowserWindow()
  win.loadURL('https://github.com')
})
```

[gui]: https://en.wikipedia.org/wiki/Graphical_user_interface
[destructuring-assignment]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00			`# Synopsis`

update excerpts based on feedback 2016-04-22 10:30:49 -07:00			`> How to use Node.js and Electron APIs.`
create a one-liner description for each API 2016-04-21 15:35:29 -07:00
Update url (#7598) * Update EventEmitter URL * Update EventEmitter URL * Enable click * Update EventEmitter URL * Update EventEmitter URL * Update URL * Update URL * Update EventEmitter URL * Tweak sentence and add perios 2016-10-13 21:09:14 +00:00			`All of [Node.js's built-in modules](https://nodejs.org/api/) are available in`
Standardize synopsis 2015-08-28 22:46:31 -07:00			`Electron and third-party node modules also fully supported as well (including`
			`the [native modules](../tutorial/using-native-node-modules.md)).`
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00
docs: Atom Shell => Electron 2015-04-16 11:31:12 +08:00			`Electron also provides some extra built-in modules for developing native`
Use "in" over "on" 2015-09-04 13:44:40 -07:00			`desktop applications. Some modules are only available in the main process, some`
Text edits 2015-09-01 15:42:10 -07:00			`are only available in the renderer process (web page), and some can be used in`
Standardize synopsis 2015-08-28 22:46:31 -07:00			`both processes.`

docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00			`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`
:memo: Fix dead urls 2018-04-09 17:58:10 -03:00			`the concept of [main process vs. renderer process](../tutorial/application-architecture.md#main-and-renderer-processes)`
:memo: Fix coding style issues * Adjust line length to `80` * Normalize whitespaces [ci skip] 2016-04-22 22:53:26 +09:00			`scripts to be able to use those modules.`
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00
Remove more words (#12852) * remove 'basically' from docs * remove 'simply' from docs * remove most uses of 'just' from docs 2018-05-08 00:16:09 -05:00			`The main process script is like a normal Node.js script:`
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00
			```javascript
chore: update to standard 12 2018-09-14 02:10:51 +10:00			`const { app, BrowserWindow } = require('electron')`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`let win = null`
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00
refactor: prefer using app.whenReady() (#21972) * docs: add references to app.whenReady() in isReady * refactor: prefer app.whenReady() In the docs, specs, and lib, replace instances of `app.once('ready')` (seen occasionally) and `app.on('ready')` (extremely common) with `app.whenReady()`. It's better to encourage users to use whenReady(): 1. it handles the edge case of registering for 'ready' after it's fired 2. it avoids the minor wart of leaving an active listener alive for an event that wll never fire again 2020-02-03 16:43:22 -06:00			`app.whenReady().then(() => {`
chore: update to standard 12 2018-09-14 02:10:51 +10:00			`win = new BrowserWindow({ width: 800, height: 600 })`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`win.loadURL('https://github.com')`
			`})`
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00			```

docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00			`The renderer process is no different than a normal web page, except for the`
			`extra ability to use node modules:`
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00
			```html
			`<!DOCTYPE html>`
			`<html>`
docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00			`<body>`
			`<script>`
chore: update to standard 12 2018-09-14 02:10:51 +10:00			`const { app } = require('electron').remote`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`console.log(app.getVersion())`
docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00			`</script>`
			`</body>`
:memo: Add Synopsis chapter. 2014-05-05 14:49:05 +08:00			`</html>`
			```

:memo: Fix dead urls 2018-04-09 17:58:10 -03:00			`To run your app, read [Run your app](../tutorial/first-app.md#running-your-app).`
docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00
			`## Destructuring assignment`

:memo: Rewrite docs on destructuring assignment [ci skip] 2016-05-04 11:59:40 -06:00			`As of 0.37, you can use`
Fix link name. 2016-03-05 23:28:39 -08:00			`[destructuring assignment][destructuring-assignment] to make it easier to use`
:memo: Rewrite docs on destructuring assignment [ci skip] 2016-05-04 11:59:40 -06:00			`built-in modules.`

			```javascript
chore: update to standard 12 2018-09-14 02:10:51 +10:00			`const { app, BrowserWindow } = require('electron')`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00
			`let win`

refactor: prefer using app.whenReady() (#21972) * docs: add references to app.whenReady() in isReady * refactor: prefer app.whenReady() In the docs, specs, and lib, replace instances of `app.once('ready')` (seen occasionally) and `app.on('ready')` (extremely common) with `app.whenReady()`. It's better to encourage users to use whenReady(): 1. it handles the edge case of registering for 'ready' after it's fired 2. it avoids the minor wart of leaving an active listener alive for an event that wll never fire again 2020-02-03 16:43:22 -06:00			`app.whenReady().then(() => {`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`win = new BrowserWindow()`
			`win.loadURL('https://github.com')`
			`})`
:memo: Rewrite docs on destructuring assignment [ci skip] 2016-05-04 11:59:40 -06:00			```

			If you need the entire `electron` module, you can require it and then using
			destructuring to access the individual modules from `electron`.
docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00
			```javascript
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`const electron = require('electron')`
chore: update to standard 12 2018-09-14 02:10:51 +10:00			`const { app, BrowserWindow } = electron`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00
			`let win`

refactor: prefer using app.whenReady() (#21972) * docs: add references to app.whenReady() in isReady * refactor: prefer app.whenReady() In the docs, specs, and lib, replace instances of `app.once('ready')` (seen occasionally) and `app.on('ready')` (extremely common) with `app.whenReady()`. It's better to encourage users to use whenReady(): 1. it handles the edge case of registering for 'ready' after it's fired 2. it avoids the minor wart of leaving an active listener alive for an event that wll never fire again 2020-02-03 16:43:22 -06:00			`app.whenReady().then(() => {`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`win = new BrowserWindow()`
			`win.loadURL('https://github.com')`
			`})`
docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00			```

:memo: Rewrite docs on destructuring assignment [ci skip] 2016-05-04 11:59:40 -06:00			`This is equivalent to the following code:`

			```javascript
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`const electron = require('electron')`
			`const app = electron.app`
			`const BrowserWindow = electron.BrowserWindow`
			`let win`

refactor: prefer using app.whenReady() (#21972) * docs: add references to app.whenReady() in isReady * refactor: prefer app.whenReady() In the docs, specs, and lib, replace instances of `app.once('ready')` (seen occasionally) and `app.on('ready')` (extremely common) with `app.whenReady()`. It's better to encourage users to use whenReady(): 1. it handles the edge case of registering for 'ready' after it's fired 2. it avoids the minor wart of leaving an active listener alive for an event that wll never fire again 2020-02-03 16:43:22 -06:00			`app.whenReady().then(() => {`
standardize all javascript blocks in English docs 2016-07-25 18:39:25 -07:00			`win = new BrowserWindow()`
			`win.loadURL('https://github.com')`
			`})`
:memo: Rewrite docs on destructuring assignment [ci skip] 2016-05-04 11:59:40 -06:00			```
docs: Add notes on old APIs 2015-11-12 22:24:11 +08:00
			`[gui]: https://en.wikipedia.org/wiki/Graphical_user_interface`
Fix link name. 2016-03-05 23:28:39 -08:00			`[destructuring-assignment]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment`