app

Control your application's event lifecycle.

Process: Main

The following example shows how to quit the application when the last window is closed:

const { app } = require('electron')

app.on('window-all-closed', () => {
  app.quit()
})

Events

The app object emits the following events:

Event: 'will-finish-launching'

Emitted when the application has finished basic startup. On Windows and Linux, the will-finish-launching event is the same as the ready event; on macOS, this event represents the applicationWillFinishLaunching notification of NSApplication.

In most cases, you should do everything in the ready event handler.

Event: 'ready'

Returns:

• event Event
• launchInfo Record<string, any> | NotificationResponse macOS

Emitted once, when Electron has finished initializing. On macOS, launchInfo holds the userInfo of the NSUserNotification or information from UNNotificationResponse that was used to open the application, if it was launched from Notification Center. You can also call app.isReady() to check if this event has already fired and app.whenReady() to get a Promise that is fulfilled when Electron is initialized.

note

The ready event is only fired after the main process has finished running the first tick of the event loop. If an Electron API needs to be called before the ready event, ensure that it is called synchronously in the top-level context of the main process.

Event: 'window-all-closed'

Emitted when all windows have been closed.

If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app; however, if you subscribe, you control whether the app quits or not. If the user pressed Cmd + Q, or the developer called app.quit(), Electron will first try to close all the windows and then emit the will-quit event, and in this case the window-all-closed event would not be emitted.

Event: 'before-quit'

Returns:

• event Event

Emitted before the application starts closing its windows. Calling event.preventDefault() will prevent the default behavior, which is terminating the application.

note

If application quit was initiated by autoUpdater.quitAndInstall(), then before-quit is emitted after emitting close event on all windows and closing them.

note

On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

Event: 'will-quit'

Returns:

• event Event

Emitted when all windows have been closed and the application will quit. Calling event.preventDefault() will prevent the default behavior, which is terminating the application.

See the description of the window-all-closed event for the differences between the will-quit and window-all-closed events.

note

On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

Event: 'quit'

Returns:

• event Event
• exitCode Integer

Emitted when the application is quitting.

note

On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

Event: 'open-file' macOS

Returns:

• event Event
• path string

Emitted when the user wants to open a file with the application. The open-file event is usually emitted when the application is already open and the OS wants to reuse the application to open the file. open-file is also emitted when a file is dropped onto the dock and the application is not yet running. Make sure to listen for the open-file event very early in your application startup to handle this case (even before the ready event is emitted).

You should call event.preventDefault() if you want to handle this event.

On Windows, you have to parse process.argv (in the main process) to get the filepath.

Event: 'open-url' macOS

Returns:

• event Event
• url string

Emitted when the user wants to open a URL with the application. Your application's Info.plist file must define the URL scheme within the CFBundleURLTypes key, and set NSPrincipalClass to AtomApplication.

As with the open-file event, be sure to register a listener for the open-url event early in your application startup to detect if the application is being opened to handle a URL. If you register the listener in response to a ready event, you'll miss URLs that trigger the launch of your application.

Event: 'activate' macOS

Returns:

• event Event
• hasVisibleWindows boolean

Emitted when the application is activated. Various actions can trigger this event, such as launching the application for the first time, attempting to re-launch the application when it's already running, or clicking on the application's dock or taskbar icon.

Event: 'did-become-active' macOS

Returns:

• event Event

Emitted when the application becomes active. This differs from the activate event in that did-become-active is emitted every time the app becomes active, not only when Dock icon is clicked or application is re-launched. It is also emitted when a user switches to the app via the macOS App Switcher.

Event: 'did-resign-active' macOS

Returns:

• event Event

Emitted when the app is no longer active and doesn’t have focus. This can be triggered, for example, by clicking on another application or by using the macOS App Switcher to switch to another application.

Event: 'continue-activity' macOS

Returns:

• event Event
• type string - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo unknown - Contains app-specific state stored by the activity on another device.
• details Object
  • webpageURL string (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.

Emitted during Handoff when an activity from a different device wants to be resumed. You should call event.preventDefault() if you want to handle this event.

A user activity can be continued only in an app that has the same developer Team ID as the activity's source app and that supports the activity's type. Supported activity types are specified in the app's Info.plist under the NSUserActivityTypes key.

Event: 'will-continue-activity' macOS

Returns:

• event Event
• type string - A string identifying the activity. Maps to NSUserActivity.activityType.

Emitted during Handoff before an activity from a different device wants to be resumed. You should call event.preventDefault() if you want to handle this event.

Event: 'continue-activity-error' macOS

Returns:

• event Event
• type string - A string identifying the activity. Maps to NSUserActivity.activityType.
• error string - A string with the error's localized description.

Emitted during Handoff when an activity from a different device fails to be resumed.

Event: 'activity-was-continued' macOS

Returns:

• event Event
• type string - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo unknown - Contains app-specific state stored by the activity.

Emitted during Handoff after an activity from this device was successfully resumed on another one.

Event: 'update-activity-state' macOS

Returns:

• event Event
• type string - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo unknown - Contains app-specific state stored by the activity.

Emitted when Handoff is about to be resumed on another device. If you need to update the state to be transferred, you should call event.preventDefault() immediately, construct a new userInfo dictionary and call app.updateCurrentActivity() in a timely manner. Otherwise, the operation will fail and continue-activity-error will be called.

Event: 'new-window-for-tab' macOS

Returns:

• event Event

Emitted when the user clicks the native macOS new tab button. The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier.

You must create a window in this handler in order for macOS tabbing to work as expected.

Event: 'browser-window-blur'

Returns:

• event Event
• window BrowserWindow

Emitted when a browserWindow gets blurred.

Event: 'browser-window-focus'

Returns:

• event Event
• window BrowserWindow

Emitted when a browserWindow gets focused.

Event: 'browser-window-created'

Returns:

• event Event
• window BrowserWindow

Emitted when a new browserWindow is created.

Event: 'web-contents-created'

Returns:

• event Event
• webContents WebContents

Emitted when a new webContents is created.

Event: 'certificate-error'

Returns:

• event Event
• webContents WebContents
• url string
• error string - The error code
• certificate Certificate
• callback Function
  • isTrusted boolean - Whether to consider the certificate as trusted
• isMainFrame boolean

Emitted when failed to verify the certificate for url, to trust the certificate you should prevent the default behavior with event.preventDefault() and call callback(true).

const { app } = require('electron')

app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
  if (url === 'https://github.com') {
    // Verification logic.
    event.preventDefault(