@electron/remote

@electron/remote lets Electron apps access main-process-only objects — like BrowserWindow, dialog, or app — directly from the renderer process, without manually wiring up IPC channels by hand. It restores the functionality of Electron’s deprecated built-in remote module as a standalone, opt-in package that must be explicitly initialized in the main process and enabled per WebContents before it can be used.

Under the hood it implements a synchronous RPC layer over Electron’s IPC: renderer-side proxies serialize method calls and property access into IPC messages, the main process resolves them against a reference-counted objects registry, and results — including callbacks and promises — are marshalled back across the process boundary. Because it reintroduces the security trade-offs of the original remote module, the maintainers frame it explicitly as a migration aid for legacy code rather than a recommended pattern for new apps.

What You Get

• Renderer-side access to main-process-only modules (BrowserWindow, dialog, app, Menu, and more) without hand-written IPC plumbing
• initialize() and enable(webContents) APIs to explicitly opt individual WebContents into remote access
• Automatic memory management via a reference-counted objects registry and WeakRef/FinalizationRegistry-based callback cleanup
• Interception events (remote-require, remote-get-global, remote-get-builtin, and window/webContents accessors) to filter or deny specific renderer requests
• TypeScript type definitions for both the main-process and renderer-process entry points

Common Use Cases

• Migrating legacy Electron codebases off the deprecated built-in remote module without a full IPC rewrite
• Quickly prototyping desktop features that need main-process APIs (native dialogs, window control) from renderer code
• Incrementally hardening an app’s security by enabling remote access only for specific trusted WebContents
• Accessing main-process singletons, like a shared app-state object, from multiple renderer windows

Under The Hood

Architecture @electron/remote splits cleanly into three layers: src/main (the RPC server in server.ts, plus objects-registry.ts for reference-counted object storage), src/renderer (the client-side proxy in remote.ts and callbacks-registry.ts), and src/common (shared serialization helpers and IPC channel constants in ipc-messages.ts). The main process exposes IPC handlers keyed by message type — require, get-global, get-builtin, member get/set/call, constructor — each resolving a remote object ID against the objects registry and converting the result to a meta-type payload. The renderer mirrors this by building JS Proxies and lazily-populated property descriptors that transparently issue synchronous IPC calls when accessed. Callbacks are handled symmetrically through paired registries backed by FinalizationRegistry on each side, so functions passed across the process boundary are dereferenced once garbage collected, limiting leaks. Because every renderer-side remote object, function call, and event depends on the shared meta-type marshalling protocol staying in lockstep between the main and renderer implementations, that protocol is the one abstraction the whole package is built around.

Tech Stack Written in TypeScript (over 99% of the codebase) with a small JavaScript surface, the package builds via tsc on prepack and declares a single peer dependency: electron >= 13.0.0. There is no runtime dependency footprint beyond what Electron itself provides — the package wraps Electron’s own ipcMain/ipcRenderer and internal V8 bindings rather than introducing its own transport. Package management is Yarn (pinned via Corepack), and publishing uses npm provenance.

Code Quality Tests run through Mocha with Chai, chai-as-promised, and dirty-chai for assertions, executed inside a real Electron process and wired into CI via a dedicated GitHub Actions workflow with a JUnit-compatible reporter. The test suite is extensive, with dozens of fixture scripts exercising specific serialization edge cases such as circular references, class instances, promises, and error properties. Error handling is explicit rather than swallowed — RPC failures are wrapped with descriptive messages and the underlying cause is preserved and re-thrown. Typing is strict TypeScript throughout, with dedicated declaration files for the public API surface.

API Design The public API intentionally mirrors Electron’s removed built-in remote module almost method-for-method, which minimizes migration effort for existing code, but adopting it still requires two non-obvious setup steps — calling initialize() in the main process and enable(webContents) per window — that aren’t discoverable from the renderer-side import alone. Documentation is concentrated almost entirely in the README, including a dedicated migration guide and explicit warnings about the security and memory-leak pitfalls of the remote pattern, rather than a separate API reference site.