Mastering Electron’s Full Lifecycle: From Launch to Exit Events

Common applications have start, activate, and close events; Electron, as a cross‑platform GUI framework, includes many more, so understanding the app, window, and page lifecycles is essential.

App launch and exit events

Events are grouped into three categories: App events, BrowserWindow events, and Renderer (Web) events.

1. App events

will-finish-launching – emitted before ready, similar to macOS applicationWillFinishLaunching. Used to listen for open-file and open-url and to start crash reporting and auto‑update.

ready – provides event and launchInfo. On macOS it follows will-finish-launching.

open-file (macOS) – must be listened to before ready; call event.preventDefault() if handling the file yourself.

open-url (macOS) – triggered when the system opens a URL with the app; call event.preventDefault() to handle it yourself and define the scheme in Info.plist.

// main.ts
// for electron-test://abc?query1=value1
app.setAsDefaultProtocolClient('electron-test');
app.on('will-finish-launching', (event) => {
  log('==> app-event: will-finish-launching <===');
  app.on('open-url', (event, url) => {
    log('==> app-event: open-url <===', url);
  });
});

activate (macOS) – emitted when the app is first launched, re‑opened, or its dock/task‑bar icon is clicked.

did-become-active – emitted when the app gains focus, e.g., after activation.

second‑instance – emitted when a second instance is started while a single‑instance lock is held; provides event, argv, and workingDirectory.

window-all-closed – emitted after all windows close; default behavior quits the app unless the event is listened to.

before-quit – emitted on any quit attempt (menu, shortcut, programmatic). Can be cancelled.

will-quit – emitted after before-quit if not cancelled.

quit – final quit event; on Windows it is not emitted for system shutdown or user log‑off.

2. BrowserWindow events

close – emitted before a window is closed; earlier than the DOM unload and beforeunload events. Use beforeunload in the renderer to handle cleanup.

window.onbeforeunload = (e) => {
  console.log('I do not want to be closed');
  e.returnValue = false; // cancel close
};

closed – asynchronous event with no arguments; indicates the window has been destroyed.

ready-to-show – emitted when the window is ready to be displayed (even if show:true).

3. Renderer (Web) events

load – emitted when the page starts loading.

window.onload = (event) => {
  console.log(event.type); // "load"
};
window.addEventListener('load', (event) => {
  console.log(event.type);
});

unload – emitted when the page is being unloaded; cannot be cancelled.

beforeunload – can cancel navigation or window close by setting event.returnValue.

DOMContentLoaded – emitted when the DOM is fully parsed.

Exit scenarios

Various ways to quit Electron:

Normal exit via Cmd+Q, Alt+F4, app.quit(), or autoUpdater.quitAndInstall().

Command‑line exit with Ctrl+C (SIGINT) or other signals (SIGTERM, SIGKILL, etc.).

Programmatic exit with app.exit() or process.exit() (triggers only quit).

Interruption via beforeunload returning false or cancelling the close event.

Example logs for a normal quit sequence:

==> app-event: will-finish-launching <===
==> app-event: session-created <===
==> app-event: web-contents-created <===
==> app-event: browser-window-created <===
==> app-event: ready <===
==> app-event: did-become-active <===
==> html-event: DOMContentLoaded <===
==> html-event: load <===
==> window-event: ready-to-show <===

==> app-event: before-quit <===
==> window-event: close <===
==> html-event: beforeunload <===
==> app-event: will-quit <===
==> app-event: quit <===
==> window-event: closed <===

When beforeunload cancels, only before-quit, close, and beforeunload fire.

Startup scenarios

Typical launches pass through will-finish-launching and ready. In single‑instance mode, app.requestSingleInstanceLock() prevents a second instance and emits second-instance with the original argv and cwd.

Command‑line launches provide arguments via process.argv and process.cwd(). URL‑scheme launches are handled by registering a protocol with app.setAsDefaultProtocolClient() and listening to open-url.

Dragging a file onto the dock (macOS) or tray triggers open-file, which must be declared in Info.plist (or extendInfo for Electron Builder).

Other notes

Opening DevTools creates an extra web-contents-created event because a new WebContents instance is spawned for the tools window.

On Windows, before-quit, will-quit, and quit are not emitted during system shutdown or user log‑off; external libraries or persistent storage are needed to handle such cases.

Calling browserWindow.destroy() only triggers the closed event; close, unload, and beforeunload are not emitted.

The code examples used in this article are available at https://github.com/yantze/electron-lifecycle-example .