`@electron/remote` is an [Electron](https://electronjs.org) module that bridges
JavaScript objects from the main process to the renderer process. This lets you
access main-process-only objects as if they were available in the renderer
process.
> ⚠️ **Warning!** This module has [many subtle
> pitfalls][remote-considered-harmful]. There is almost always a better way to
> accomplish your task than using this module. For example, [`ipcRenderer.invoke`](https://www.electronjs.org/docs/api/ipc-renderer#ipcrendererinvokechannel-args) can serve many common use cases.
`@electron/remote` is a replacement for the built-in `remote` module in
Electron, which is deprecated and will eventually be removed.
## Migrating from `remote`
> **NOTE:**`@electron/remote` requires Electron 10 or higher.
There are three things you need to do to migrate from the built-in `remote`
module to `@electron/remote`.
First, you need to install it from NPM:
```shell
$ npm install --save @electron/remote
```
Second, `@electron/remote/main` must be initialized in the main
process before it can be used from the renderer:
```javascript
// in the main process:
require('@electron/remote/main').initialize()
```
Third, `require('electron').remote` in the renderer process must be
**Note:** Since this is requiring a module through npm rather than a built-in
module, if you're using `remote` from a sandboxed process, you'll need to
configure your bundler appropriately to package the code of `@electron/remote`
in the preload script. Of course, [using `@electron/remote` makes the sandbox
much less effective][remote-considered-harmful].
**Note:** In `electron >= 14.0.0`, you must use the new `enable` API to enable the remote module for each desired `WebContents` separately: `require("@electron/remote/main").enable(webContents)`.
In `electron < 14.0.0`, `@electron/remote` respects the `enableRemoteModule` WebPreferences
value. You must pass `{ webPreferences: { enableRemoteModule: true } }` to
the constructor of `BrowserWindow`s that should be granted permission to use
`@electron/remote`.
# API Reference
The `remote` module provides a simple way to do inter-process communication
(IPC) between the renderer process (web page) and the main process.
In Electron, GUI-related modules (such as `dialog`, `menu` etc.) are only
available in the main process, not in the renderer process. In order to use them
from the renderer process, the `ipc` module is necessary to send inter-process
messages to the main process. With the `remote` module, you can invoke methods
of the main process object without explicitly sending inter-process messages,
similar to Java's [RMI][rmi]. An example of creating a browser window from a
let win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')
```
In order for this to work, you first need to initialize the main-process side
of the remote module:
```javascript
// in the main process:
require('@electron/remote/main').initialize()
```
**Note:** In `electron >= 14.0.0` the remote module is disabled by default for any `WebContents` instance and is only enabled for specified `WebContents` after explicitly calling `require("@electron/remote/main").enable(webContents)`.
In `electron < 14.0.0` the remote module can be disabled for security reasons in the following contexts:
- [`BrowserWindow`](browser-window.md) - by setting the `enableRemoteModule` option to `false`.
- [`<webview>`](webview-tag.md) - by setting the `enableremotemodule` attribute to `false`.
## Remote Objects
Each object (including functions) returned by the `remote` module represents an
object in the main process (we call it a remote object or remote function).
When you invoke methods of a remote object, call a remote function, or create
a new object with the remote constructor (function), you are actually sending
synchronous inter-process messages.
In the example above, both `BrowserWindow` and `win` were remote objects and
`new BrowserWindow` didn't create a `BrowserWindow` object in the renderer
process. Instead, it created a `BrowserWindow` object in the main process and
returned the corresponding remote object in the renderer process, namely the
`win` object.
**Note:** Only [enumerable properties][enumerable-properties] which are present
when the remote object is first referenced are accessible via remote.
**Note:** Arrays and Buffers are copied over IPC when accessed via the `remote`
module. Modifying them in the renderer process does not modify them in the main
process and vice versa.
## Lifetime of Remote Objects
Electron makes sure that as long as the remote object in the renderer process
lives (in other words, has not been garbage collected), the corresponding object
in the main process will not be released. When the remote object has been
garbage collected, the corresponding object in the main process will be
dereferenced.
If the remote object is leaked in the renderer process (e.g. stored in a map but
never freed), the corresponding object in the main process will also be leaked,
so you should be very careful not to leak remote objects.
Primary value types like strings and numbers, however, are sent by copy.
## Passing callbacks to the main process
Code in the main process can accept callbacks from the renderer - for instance
the `remote` module - but you should be extremely careful when using this
feature.
First, in order to avoid deadlocks, the callbacks passed to the main process
are called asynchronously. You should not expect the main process to
get the return value of the passed callbacks.
For instance you can't use a function from the renderer process in an
