From c83f836faf1888ab3eb443bf719c054bcc7e4e1b Mon Sep 17 00:00:00 2001
From: Charles Kerr <ckerr@github.com>
Date: Mon, 3 Feb 2020 16:43:22 -0600
Subject: [PATCH] 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
---
 docs/api/accelerator.md                       |  2 +-
 docs/api/app.md                               | 12 ++++++----
 docs/api/command-line-switches.md             |  2 +-
 docs/api/content-tracing.md                   |  2 +-
 docs/api/global-shortcut.md                   |  2 +-
 docs/api/net-log.md                           |  2 +-
 docs/api/net.md                               |  2 +-
 docs/api/power-monitor.md                     |  2 +-
 docs/api/protocol-ns.md                       |  4 ++--
 docs/api/protocol.md                          |  4 ++--
 docs/api/remote.md                            |  2 +-
 docs/api/sandbox-option.md                    |  6 ++---
 docs/api/screen.md                            |  4 ++--
 docs/api/session.md                           |  4 ++--
 docs/api/synopsis.md                          |  8 +++----
 docs/api/touch-bar.md                         |  2 +-
 docs/api/tray.md                              |  4 ++--
 docs/api/web-contents.md                      |  6 ++---
 docs/faq.md                                   |  4 ++--
 .../asynchronous-messages/main.js             |  2 +-
 .../synchronous-messages/main.js              |  2 +-
 .../media/screenshot/take-screenshot/main.js  |  2 +-
 docs/fiddles/menus/customize-menus/main.js    |  2 +-
 docs/fiddles/menus/shortcuts/main.js          |  2 +-
 .../native-ui/dialogs/error-dialog/main.js    |  2 +-
 .../dialogs/information-dialog/main.js        |  2 +-
 .../dialogs/open-file-or-directory/main.js    |  2 +-
 .../native-ui/dialogs/save-dialog/main.js     |  2 +-
 docs/fiddles/native-ui/drag-and-drop/main.js  |  2 +-
 .../external-links/main.js                    |  2 +-
 .../external-links-file-manager/main.js       |  2 +-
 .../path-in-file-manager/main.js              |  2 +-
 .../notifications/basic-notification/main.js  |  2 +-
 docs/fiddles/native-ui/notifications/main.js  |  2 +-
 .../notification-with-image/main.js           |  2 +-
 docs/fiddles/native-ui/tray/main.js           |  2 +-
 docs/fiddles/screen/fit-screen/main.js        |  2 +-
 docs/fiddles/system/clipboard/copy/main.js    |  2 +-
 docs/fiddles/system/clipboard/paste/main.js   |  2 +-
 .../main.js                                   |  2 +-
 .../get-version-information/main.js           |  2 +-
 .../create-frameless-window/main.js           |  2 +-
 .../manage-windows/frameless-window/main.js   |  2 +-
 .../manage-window-state/main.js               |  2 +-
 .../windows/manage-windows/new-window/main.js |  2 +-
 .../manage-windows/window-events/main.js      |  2 +-
 docs/tutorial/first-app.md                    |  4 ++--
 docs/tutorial/keyboard-shortcuts.md           |  2 +-
 docs/tutorial/offscreen-rendering.md          |  2 +-
 docs/tutorial/online-offline-events.md        |  4 ++--
 docs/tutorial/testing-widevine-cdm.md         |  2 +-
 docs/tutorial/using-pepper-flash-plugin.md    |  2 +-
 lib/browser/chrome-extension-shim.js          |  2 +-
 lib/browser/chrome-extension.js               |  2 +-
 lib/browser/init.ts                           |  2 +-
 .../fixtures/api/ipc-main-listeners/main.js   |  2 +-
 .../fixtures/api/leak-exit-browserview.js     |  2 +-
 .../fixtures/api/leak-exit-webcontentsview.js |  2 +-
 spec-main/fixtures/api/net-log/main.js        |  2 +-
 spec-main/fixtures/api/test-menu-null/main.js |  2 +-
 .../fixtures/api/test-menu-visibility/main.js |  2 +-
 spec/fixtures/api/command-line/main.js        |  2 +-
 spec/fixtures/api/cookie-app/main.js          |  2 +-
 spec/fixtures/api/default-menu/main.js        |  2 +-
 .../api/exit-closes-all-windows-app/main.js   |  2 +-
 spec/fixtures/api/gpu-info.js                 |  2 +-
 spec/fixtures/api/leak-exit-webcontents.js    |  2 +-
 spec/fixtures/api/locale-check/main.js        |  2 +-
 spec/fixtures/api/mixed-sandbox-app/main.js   |  2 +-
 spec/fixtures/api/quit-app/main.js            |  2 +-
 spec/fixtures/api/relaunch/main.js            |  2 +-
 spec/fixtures/api/singleton/main.js           |  2 +-
 spec/fixtures/api/window-all-closed/main.js   |  2 +-
 spec/fixtures/no-proprietary-codecs.js        |  2 +-
 .../fixtures/snapshot-items-available/main.js |  2 +-
 spec/static/main.js                           |  2 +-
 spec/ts-smoke/electron/main.ts                | 24 +++++++++----------
 spec/ts-smoke/electron/renderer.ts            |  4 ++--
 78 files changed, 111 insertions(+), 109 deletions(-)

diff --git a/docs/api/accelerator.md b/docs/api/accelerator.md
index 7bbccd4bc5..8a5b1c92e3 100644
--- a/docs/api/accelerator.md
+++ b/docs/api/accelerator.md
@@ -18,7 +18,7 @@ method, i.e.
 ```javascript
 const { app, globalShortcut } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   // Register a 'CommandOrControl+Y' shortcut listener.
   globalShortcut.register('CommandOrControl+Y', () => {
     // Do stuff when Y and either Command/Control is pressed.
diff --git a/docs/api/app.md b/docs/api/app.md
index 67167fd18e..7c701add7a 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -34,10 +34,11 @@ Returns:
 
 * `launchInfo` unknown _macOS_
 
-Emitted when Electron has finished initializing. On macOS, `launchInfo` holds
-the `userInfo` of the `NSUserNotification` that was used to open the application,
-if it was launched from Notification Center. You can call `app.isReady()` to
-check if this event has already fired.
+Emitted once, when Electron has finished initializing. On macOS, `launchInfo`
+holds the `userInfo` of the `NSUserNotification` 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.
 
 ### Event: 'window-all-closed'
 
@@ -545,6 +546,7 @@ app.exit(0)
 ### `app.isReady()`
 
 Returns `Boolean` - `true` if Electron has finished initializing, `false` otherwise.
+See also `app.whenReady()`.
 
 ### `app.whenReady()`
 
@@ -935,7 +937,7 @@ if (!gotTheLock) {
   })
 
   // Create myWindow, load the rest of the app, etc...
-  app.on('ready', () => {
+  app.whenReady().then(() => {
   })
 }
 ```
diff --git a/docs/api/command-line-switches.md b/docs/api/command-line-switches.md
index 2a86961609..f836ac5548 100644
--- a/docs/api/command-line-switches.md
+++ b/docs/api/command-line-switches.md
@@ -11,7 +11,7 @@ const { app } = require('electron')
 app.commandLine.appendSwitch('remote-debugging-port', '8315')
 app.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   // Your code here
 })
 ```
diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md
index f44e474f14..11c4213f84 100644
--- a/docs/api/content-tracing.md
+++ b/docs/api/content-tracing.md
@@ -13,7 +13,7 @@ module is emitted.
 ```javascript
 const { app, contentTracing } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   (async () => {
     await contentTracing.startRecording({
       include_categories: ['*']
diff --git a/docs/api/global-shortcut.md b/docs/api/global-shortcut.md
index 3d18a39f5c..7826390176 100644
--- a/docs/api/global-shortcut.md
+++ b/docs/api/global-shortcut.md
@@ -15,7 +15,7 @@ event of the app module is emitted.
 ```javascript
 const { app, globalShortcut } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   // Register a 'CommandOrControl+X' shortcut listener.
   const ret = globalShortcut.register('CommandOrControl+X', () => {
     console.log('CommandOrControl+X is pressed')
diff --git a/docs/api/net-log.md b/docs/api/net-log.md
index 0994416c2a..2371b8f580 100644
--- a/docs/api/net-log.md
+++ b/docs/api/net-log.md
@@ -7,7 +7,7 @@ Process: [Main](../glossary.md#main-process)
 ```javascript
 const { netLog } = require('electron')
 
-app.on('ready', async () => {
+app.whenReady().then(async () => {
   await netLog.startLogging('/path/to/net-log')
   // After some network events
   const path = await netLog.stopLogging()
diff --git a/docs/api/net.md b/docs/api/net.md
index f4b434f373..43ebc3e0cd 100644
--- a/docs/api/net.md
+++ b/docs/api/net.md
@@ -28,7 +28,7 @@ Example usage:
 
 ```javascript
 const { app } = require('electron')
-app.on('ready', () => {
+app.whenReady().then(() => {
   const { net } = require('electron')
   const request = net.request('https://github.com')
   request.on('response', (response) => {
diff --git a/docs/api/power-monitor.md b/docs/api/power-monitor.md
index a2bf7eb303..eadcd5e729 100644
--- a/docs/api/power-monitor.md
+++ b/docs/api/power-monitor.md
@@ -13,7 +13,7 @@ For example:
 ```javascript
 const { app, powerMonitor } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   powerMonitor.on('suspend', () => {
     console.log('The system is going to sleep')
   })
diff --git a/docs/api/protocol-ns.md b/docs/api/protocol-ns.md
index 45a96f4511..536e77051a 100644
--- a/docs/api/protocol-ns.md
+++ b/docs/api/protocol-ns.md
@@ -20,7 +20,7 @@ An example of implementing a protocol that has the same effect as the
 const { app, protocol } = require('electron')
 const path = require('path')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   protocol.registerFileProtocol('atom', (request, callback) => {
     const url = request.url.substr(7)
     callback({ path: path.normalize(`${__dirname}/${url}`) })
@@ -47,7 +47,7 @@ to register it to that session explicitly.
 const { session, app, protocol } = require('electron')
 const path = require('path')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const partition = 'persist:example'
   const ses = session.fromPartition(partition)
 
diff --git a/docs/api/protocol.md b/docs/api/protocol.md
index 5da297c3c2..b93b0b6a49 100644
--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@@ -11,7 +11,7 @@ An example of implementing a protocol that has the same effect as the
 const { app, protocol } = require('electron')
 const path = require('path')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   protocol.registerFileProtocol('atom', (request, callback) => {
     const url = request.url.substr(7)
     callback({ path: path.normalize(`${__dirname}/${url}`) })
@@ -34,7 +34,7 @@ To have your custom protocol work in combination with a custom session, you need
 const { session, app, protocol } = require('electron')
 const path = require('path')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const partition = 'persist:example'
   const ses = session.fromPartition(partition)
 
diff --git a/docs/api/remote.md b/docs/api/remote.md
index e49e738ffb..75c5c13a56 100644
--- a/docs/api/remote.md
+++ b/docs/api/remote.md
@@ -163,7 +163,7 @@ project/
 ```js
 // main process: main/index.js
 const { app } = require('electron')
-app.on('ready', () => { /* ... */ })
+app.whenReady().then(() => { /* ... */ })
 ```
 
 ```js
diff --git a/docs/api/sandbox-option.md b/docs/api/sandbox-option.md
index 6fb46d31ff..414a308da6 100644
--- a/docs/api/sandbox-option.md
+++ b/docs/api/sandbox-option.md
@@ -39,7 +39,7 @@ To create a sandboxed window, pass `sandbox: true` to `webPreferences`:
 
 ```js
 let win
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow({
     webPreferences: {
       sandbox: true
@@ -59,7 +59,7 @@ and returns a proxy to this via `window.open`).
 ```js
 let win
 app.enableSandbox()
-app.on('ready', () => {
+app.whenReady().then(() => {
   // no need to pass `sandbox: true` since `app.enableSandbox()` was called.
   win = new BrowserWindow()
   win.loadURL('http://google.com')
@@ -73,7 +73,7 @@ Here's an example:
 
 ```js
 let win
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow({
     webPreferences: {
       sandbox: true,
diff --git a/docs/api/screen.md b/docs/api/screen.md
index 290a4a690d..0fbfa00cbe 100644
--- a/docs/api/screen.md
+++ b/docs/api/screen.md
@@ -18,7 +18,7 @@ An example of creating a window that fills the whole screen:
 const { app, BrowserWindow, screen } = require('electron')
 
 let win
-app.on('ready', () => {
+app.whenReady().then(() => {
   const { width, height } = screen.getPrimaryDisplay().workAreaSize
   win = new BrowserWindow({ width, height })
   win.loadURL('https://github.com')
@@ -32,7 +32,7 @@ const { app, BrowserWindow, screen } = require('electron')
 
 let win
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   let displays = screen.getAllDisplays()
   let externalDisplay = displays.find((display) => {
     return display.bounds.x !== 0 || display.bounds.y !== 0
diff --git a/docs/api/session.md b/docs/api/session.md
index 22af38488b..3cc8ff5b63 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -579,7 +579,7 @@ A [`Protocol`](protocol.md) object for this session.
 const { app, session } = require('electron')
 const path = require('path')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const protocol = session.fromPartition('some-partition').protocol
   protocol.registerFileProtocol('atom', (request, callback) => {
     let url = request.url.substr(7)
@@ -597,7 +597,7 @@ A [`NetLog`](net-log.md) object for this session.
 ```javascript
 const { app, session } = require('electron')
 
-app.on('ready', async () => {
+app.whenReady().then(async () => {
   const netLog = session.fromPartition('some-partition').netLog
   netLog.startLogging('/path/to/net-log')
   // After some network events
diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md
index 8b3ea56094..6ee64e6762 100644
--- a/docs/api/synopsis.md
+++ b/docs/api/synopsis.md
@@ -22,7 +22,7 @@ The main process script is like a normal Node.js script:
 const { app, BrowserWindow } = require('electron')
 let win = null
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow({ width: 800, height: 600 })
   win.loadURL('https://github.com')
 })
@@ -56,7 +56,7 @@ const { app, BrowserWindow } = require('electron')
 
 let win
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow()
   win.loadURL('https://github.com')
 })
@@ -71,7 +71,7 @@ const { app, BrowserWindow } = electron
 
 let win
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow()
   win.loadURL('https://github.com')
 })
@@ -85,7 +85,7 @@ const app = electron.app
 const BrowserWindow = electron.BrowserWindow
 let win
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow()
   win.loadURL('https://github.com')
 })
diff --git a/docs/api/touch-bar.md b/docs/api/touch-bar.md
index 28194d67c0..5764ebc6a8 100644
--- a/docs/api/touch-bar.md
+++ b/docs/api/touch-bar.md
@@ -166,7 +166,7 @@ const touchBar = new TouchBar({
 
 let window
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   window = new BrowserWindow({
     frame: false,
     titleBarStyle: 'hiddenInset',
diff --git a/docs/api/tray.md b/docs/api/tray.md
index 794d5fdcf5..98e6d5ac89 100644
--- a/docs/api/tray.md
+++ b/docs/api/tray.md
@@ -10,7 +10,7 @@ Process: [Main](../glossary.md#main-process)
 const { app, Menu, Tray } = require('electron')
 
 let tray = null
-app.on('ready', () => {
+app.whenReady().then(() => {
   tray = new Tray('/path/to/my/icon')
   const contextMenu = Menu.buildFromTemplate([
     { label: 'Item1', type: 'radio' },
@@ -38,7 +38,7 @@ __Platform limitations:__
 const { app, Menu, Tray } = require('electron')
 
 let appIcon = null
-app.on('ready', () => {
+app.whenReady().then(() => {
   appIcon = new Tray('/path/to/my/icon')
   const contextMenu = Menu.buildFromTemplate([
     { label: 'Item1', type: 'radio' },
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index f0496ee77b..45316522fc 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -624,7 +624,7 @@ const { app, BrowserWindow } = require('electron')
 let win = null
 app.commandLine.appendSwitch('enable-experimental-web-platform-features')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow({ width: 800, height: 600 })
   win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
     event.preventDefault()
@@ -1444,7 +1444,7 @@ const { app, BrowserWindow } = require('electron')
 let win = null
 let devtools = null
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow()
   devtools = new BrowserWindow()
   win.loadURL('https://github.com')
@@ -1533,7 +1533,7 @@ An example of sending messages from the main process to the renderer process:
 const { app, BrowserWindow } = require('electron')
 let win = null
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow({ width: 800, height: 600 })
   win.loadURL(`file://${__dirname}/index.html`)
   win.webContents.on('did-finish-load', () => {
diff --git a/docs/faq.md b/docs/faq.md
index 0354182a0c..fae73e3f95 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -79,7 +79,7 @@ code from this:
 
 ```javascript
 const { app, Tray } = require('electron')
-app.on('ready', () => {
+app.whenReady().then(() => {
   const tray = new Tray('/path/to/icon.png')
   tray.setTitle('hello world')
 })
@@ -90,7 +90,7 @@ to this:
 ```javascript
 const { app, Tray } = require('electron')
 let tray = null
-app.on('ready', () => {
+app.whenReady().then(() => {
   tray = new Tray('/path/to/icon.png')
   tray.setTitle('hello world')
 })
diff --git a/docs/fiddles/communication/two-processes/asynchronous-messages/main.js b/docs/fiddles/communication/two-processes/asynchronous-messages/main.js
index 38dc956f39..942f7022f8 100644
--- a/docs/fiddles/communication/two-processes/asynchronous-messages/main.js
+++ b/docs/fiddles/communication/two-processes/asynchronous-messages/main.js
@@ -20,7 +20,7 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
 
diff --git a/docs/fiddles/communication/two-processes/synchronous-messages/main.js b/docs/fiddles/communication/two-processes/synchronous-messages/main.js
index 70db43febd..1adb7c02c9 100644
--- a/docs/fiddles/communication/two-processes/synchronous-messages/main.js
+++ b/docs/fiddles/communication/two-processes/synchronous-messages/main.js
@@ -20,7 +20,7 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
 
diff --git a/docs/fiddles/media/screenshot/take-screenshot/main.js b/docs/fiddles/media/screenshot/take-screenshot/main.js
index 37adb5d2b9..a08035b335 100644
--- a/docs/fiddles/media/screenshot/take-screenshot/main.js
+++ b/docs/fiddles/media/screenshot/take-screenshot/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/menus/customize-menus/main.js b/docs/fiddles/menus/customize-menus/main.js
index ad18f25f59..38774c6374 100644
--- a/docs/fiddles/menus/customize-menus/main.js
+++ b/docs/fiddles/menus/customize-menus/main.js
@@ -316,7 +316,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
   const menu = Menu.buildFromTemplate(template)
   Menu.setApplicationMenu(menu)
diff --git a/docs/fiddles/menus/shortcuts/main.js b/docs/fiddles/menus/shortcuts/main.js
index b2c4d55901..5c8a725c4b 100644
--- a/docs/fiddles/menus/shortcuts/main.js
+++ b/docs/fiddles/menus/shortcuts/main.js
@@ -42,7 +42,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/dialogs/error-dialog/main.js b/docs/fiddles/native-ui/dialogs/error-dialog/main.js
index 7b46005e85..5add46041e 100644
--- a/docs/fiddles/native-ui/dialogs/error-dialog/main.js
+++ b/docs/fiddles/native-ui/dialogs/error-dialog/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/dialogs/information-dialog/main.js b/docs/fiddles/native-ui/dialogs/information-dialog/main.js
index 30a360fd87..d69953df67 100644
--- a/docs/fiddles/native-ui/dialogs/information-dialog/main.js
+++ b/docs/fiddles/native-ui/dialogs/information-dialog/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/dialogs/open-file-or-directory/main.js b/docs/fiddles/native-ui/dialogs/open-file-or-directory/main.js
index 12b5909a36..bb6b83cc19 100644
--- a/docs/fiddles/native-ui/dialogs/open-file-or-directory/main.js
+++ b/docs/fiddles/native-ui/dialogs/open-file-or-directory/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/dialogs/save-dialog/main.js b/docs/fiddles/native-ui/dialogs/save-dialog/main.js
index 3ed95a8c32..9825acbad5 100644
--- a/docs/fiddles/native-ui/dialogs/save-dialog/main.js
+++ b/docs/fiddles/native-ui/dialogs/save-dialog/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/drag-and-drop/main.js b/docs/fiddles/native-ui/drag-and-drop/main.js
index be3dcf9ec3..ef865e22b6 100644
--- a/docs/fiddles/native-ui/drag-and-drop/main.js
+++ b/docs/fiddles/native-ui/drag-and-drop/main.js
@@ -32,7 +32,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/external-links-file-manager/external-links/main.js b/docs/fiddles/native-ui/external-links-file-manager/external-links/main.js
index 2061823025..8c60edf69f 100644
--- a/docs/fiddles/native-ui/external-links-file-manager/external-links/main.js
+++ b/docs/fiddles/native-ui/external-links-file-manager/external-links/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/native-ui/external-links-file-manager/main.js b/docs/fiddles/native-ui/external-links-file-manager/main.js
index 4fff6140a0..7f599a744c 100644
--- a/docs/fiddles/native-ui/external-links-file-manager/main.js
+++ b/docs/fiddles/native-ui/external-links-file-manager/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/external-links-file-manager/path-in-file-manager/main.js b/docs/fiddles/native-ui/external-links-file-manager/path-in-file-manager/main.js
index c78f16abc8..9246b95bb2 100644
--- a/docs/fiddles/native-ui/external-links-file-manager/path-in-file-manager/main.js
+++ b/docs/fiddles/native-ui/external-links-file-manager/path-in-file-manager/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/native-ui/notifications/basic-notification/main.js b/docs/fiddles/native-ui/notifications/basic-notification/main.js
index 78603a253c..b05ea9cbcc 100644
--- a/docs/fiddles/native-ui/notifications/basic-notification/main.js
+++ b/docs/fiddles/native-ui/notifications/basic-notification/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/native-ui/notifications/main.js b/docs/fiddles/native-ui/notifications/main.js
index 4fff6140a0..7f599a744c 100644
--- a/docs/fiddles/native-ui/notifications/main.js
+++ b/docs/fiddles/native-ui/notifications/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/native-ui/notifications/notification-with-image/main.js b/docs/fiddles/native-ui/notifications/notification-with-image/main.js
index 997426d592..40c6001a99 100644
--- a/docs/fiddles/native-ui/notifications/notification-with-image/main.js
+++ b/docs/fiddles/native-ui/notifications/notification-with-image/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/native-ui/tray/main.js b/docs/fiddles/native-ui/tray/main.js
index 14a6f96249..f723e388fc 100644
--- a/docs/fiddles/native-ui/tray/main.js
+++ b/docs/fiddles/native-ui/tray/main.js
@@ -34,7 +34,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/screen/fit-screen/main.js b/docs/fiddles/screen/fit-screen/main.js
index 2577553e95..8fbaabcc5b 100644
--- a/docs/fiddles/screen/fit-screen/main.js
+++ b/docs/fiddles/screen/fit-screen/main.js
@@ -7,7 +7,7 @@ const { app, BrowserWindow } = require('electron')
 
 let mainWindow = null
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   // We cannot require the screen module until the app is ready.
   const { screen } = require('electron')
 
diff --git a/docs/fiddles/system/clipboard/copy/main.js b/docs/fiddles/system/clipboard/copy/main.js
index ac2cc27208..36ad14197f 100644
--- a/docs/fiddles/system/clipboard/copy/main.js
+++ b/docs/fiddles/system/clipboard/copy/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/system/clipboard/paste/main.js b/docs/fiddles/system/clipboard/paste/main.js
index 263c4c5c50..b0883e6f4e 100644
--- a/docs/fiddles/system/clipboard/paste/main.js
+++ b/docs/fiddles/system/clipboard/paste/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/main.js b/docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/main.js
index f52b46b4dd..ef56ec2710 100644
--- a/docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/main.js
+++ b/docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/main.js
@@ -34,7 +34,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/system/system-information/get-version-information/main.js b/docs/fiddles/system/system-information/get-version-information/main.js
index 1f9f91774c..daf87d0fda 100644
--- a/docs/fiddles/system/system-information/get-version-information/main.js
+++ b/docs/fiddles/system/system-information/get-version-information/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/windows/manage-windows/create-frameless-window/main.js b/docs/fiddles/windows/manage-windows/create-frameless-window/main.js
index e6183c5ff5..355f3591f8 100644
--- a/docs/fiddles/windows/manage-windows/create-frameless-window/main.js
+++ b/docs/fiddles/windows/manage-windows/create-frameless-window/main.js
@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
diff --git a/docs/fiddles/windows/manage-windows/frameless-window/main.js b/docs/fiddles/windows/manage-windows/frameless-window/main.js
index 4fff6140a0..7f599a744c 100644
--- a/docs/fiddles/windows/manage-windows/frameless-window/main.js
+++ b/docs/fiddles/windows/manage-windows/frameless-window/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/windows/manage-windows/manage-window-state/main.js b/docs/fiddles/windows/manage-windows/manage-window-state/main.js
index 4fff6140a0..7f599a744c 100644
--- a/docs/fiddles/windows/manage-windows/manage-window-state/main.js
+++ b/docs/fiddles/windows/manage-windows/manage-window-state/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/windows/manage-windows/new-window/main.js b/docs/fiddles/windows/manage-windows/new-window/main.js
index 1297177f2d..2bb580355e 100644
--- a/docs/fiddles/windows/manage-windows/new-window/main.js
+++ b/docs/fiddles/windows/manage-windows/new-window/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/fiddles/windows/manage-windows/window-events/main.js b/docs/fiddles/windows/manage-windows/window-events/main.js
index 4fff6140a0..7f599a744c 100644
--- a/docs/fiddles/windows/manage-windows/window-events/main.js
+++ b/docs/fiddles/windows/manage-windows/window-events/main.js
@@ -33,7 +33,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', function () {
diff --git a/docs/tutorial/first-app.md b/docs/tutorial/first-app.md
index 06a25d5ef9..ddadc58766 100644
--- a/docs/tutorial/first-app.md
+++ b/docs/tutorial/first-app.md
@@ -121,7 +121,7 @@ function createWindow () {
   win.loadFile('index.html')
 }
 
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 ```
 
 The `main.js` should create windows and handle all the system events your
@@ -152,7 +152,7 @@ function createWindow () {
 // This method will be called when Electron has finished
 // initialization and is ready to create browser windows.
 // Some APIs can only be used after this event occurs.
-app.on('ready', createWindow)
+app.whenReady().then(createWindow)
 
 // Quit when all windows are closed.
 app.on('window-all-closed', () => {
diff --git a/docs/tutorial/keyboard-shortcuts.md b/docs/tutorial/keyboard-shortcuts.md
index cc3736a7df..b61a460771 100644
--- a/docs/tutorial/keyboard-shortcuts.md
+++ b/docs/tutorial/keyboard-shortcuts.md
@@ -35,7 +35,7 @@ the application does not have keyboard focus.
 ```js
 const { app, globalShortcut } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   globalShortcut.register('CommandOrControl+X', () => {
     console.log('CommandOrControl+X is pressed')
   })
diff --git a/docs/tutorial/offscreen-rendering.md b/docs/tutorial/offscreen-rendering.md
index a991395c02..74bfff02be 100644
--- a/docs/tutorial/offscreen-rendering.md
+++ b/docs/tutorial/offscreen-rendering.md
@@ -41,7 +41,7 @@ app.disableHardwareAcceleration()
 
 let win
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow({
     webPreferences: {
       offscreen: true
diff --git a/docs/tutorial/online-offline-events.md b/docs/tutorial/online-offline-events.md
index ae5d5d07ac..eb36ac18ce 100644
--- a/docs/tutorial/online-offline-events.md
+++ b/docs/tutorial/online-offline-events.md
@@ -15,7 +15,7 @@ const { app, BrowserWindow } = require('electron')
 
 let onlineStatusWindow
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false })
   onlineStatusWindow.loadURL(`file://${__dirname}/online-status.html`)
 })
@@ -53,7 +53,7 @@ _main.js_
 const { app, BrowserWindow, ipcMain } = require('electron')
 let onlineStatusWindow
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false, webPreferences: { nodeIntegration: true } })
   onlineStatusWindow.loadURL(`file://${__dirname}/online-status.html`)
 })
diff --git a/docs/tutorial/testing-widevine-cdm.md b/docs/tutorial/testing-widevine-cdm.md
index cbae6beb42..4be3025634 100644
--- a/docs/tutorial/testing-widevine-cdm.md
+++ b/docs/tutorial/testing-widevine-cdm.md
@@ -79,7 +79,7 @@ app.commandLine.appendSwitch('widevine-cdm-path', '/path/to/widevine_library')
 app.commandLine.appendSwitch('widevine-cdm-version', '1.4.8.866')
 
 let win = null
-app.on('ready', () => {
+app.whenReady().then(() => {
   win = new BrowserWindow()
   win.show()
 })
diff --git a/docs/tutorial/using-pepper-flash-plugin.md b/docs/tutorial/using-pepper-flash-plugin.md
index d432785bdc..350eeb65b8 100644
--- a/docs/tutorial/using-pepper-flash-plugin.md
+++ b/docs/tutorial/using-pepper-flash-plugin.md
@@ -41,7 +41,7 @@ app.commandLine.appendSwitch('ppapi-flash-path', path.join(__dirname, pluginName
 // Optional: Specify flash version, for example, v17.0.0.169
 app.commandLine.appendSwitch('ppapi-flash-version', '17.0.0.169')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   let win = new BrowserWindow({
     width: 800,
     height: 600,
diff --git a/lib/browser/chrome-extension-shim.js b/lib/browser/chrome-extension-shim.js
index c9e0035178..8eecd67b46 100644
--- a/lib/browser/chrome-extension-shim.js
+++ b/lib/browser/chrome-extension-shim.js
@@ -10,7 +10,7 @@ if (!process.electronBinding('features').isExtensionsEnabled()) {
 
 const { app, session, BrowserWindow, deprecate } = require('electron')
 
-app.once('ready', function () {
+app.whenReady().then(function () {
   const addExtension = function (srcDirectory) {
     return session.defaultSession.loadExtension(srcDirectory)
   }
diff --git a/lib/browser/chrome-extension.js b/lib/browser/chrome-extension.js
index 8b9c263347..2bb9c4e5f5 100644
--- a/lib/browser/chrome-extension.js
+++ b/lib/browser/chrome-extension.js
@@ -466,7 +466,7 @@ app.on('will-quit', function () {
 })
 
 // We can not use protocol or BrowserWindow until app is ready.
-app.once('ready', function () {
+app.whenReady().then(function () {
   // The public API to add/remove extensions.
   BrowserWindow.addExtension = function (srcDirectory) {
     const manifest = getManifestFromPath(srcDirectory)
diff --git a/lib/browser/init.ts b/lib/browser/init.ts
index 9d35e5b895..b23677be37 100644
--- a/lib/browser/init.ts
+++ b/lib/browser/init.ts
@@ -204,7 +204,7 @@ const { setDefaultApplicationMenu } = require('@electron/internal/browser/defaul
 // Note that the task must be added before loading any app, so we can make sure
 // the call is maded before any user window is created, otherwise the default
 // menu may show even when user explicitly hides the menu.
-app.once('ready', setDefaultApplicationMenu)
+app.whenReady().then(setDefaultApplicationMenu)
 
 if (packagePath) {
   // Finally load app's main.js and transfer control to C++.
diff --git a/spec-main/fixtures/api/ipc-main-listeners/main.js b/spec-main/fixtures/api/ipc-main-listeners/main.js
index afb459f74f..52d71d2228 100644
--- a/spec-main/fixtures/api/ipc-main-listeners/main.js
+++ b/spec-main/fixtures/api/ipc-main-listeners/main.js
@@ -1,6 +1,6 @@
 const { app, ipcMain } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   process.stdout.write(JSON.stringify(ipcMain.eventNames()))
   process.stdout.end()
 
diff --git a/spec-main/fixtures/api/leak-exit-browserview.js b/spec-main/fixtures/api/leak-exit-browserview.js
index 8e5d5d2eb5..8b172555b2 100644
--- a/spec-main/fixtures/api/leak-exit-browserview.js
+++ b/spec-main/fixtures/api/leak-exit-browserview.js
@@ -1,5 +1,5 @@
 const { BrowserView, app } = require('electron')
-app.on('ready', function () {
+app.whenReady().then(function () {
   new BrowserView({})  // eslint-disable-line
 
   app.quit()
diff --git a/spec-main/fixtures/api/leak-exit-webcontentsview.js b/spec-main/fixtures/api/leak-exit-webcontentsview.js
index cec51aeef2..74b854c34f 100644
--- a/spec-main/fixtures/api/leak-exit-webcontentsview.js
+++ b/spec-main/fixtures/api/leak-exit-webcontentsview.js
@@ -1,5 +1,5 @@
 const { WebContentsView, app, webContents } = require('electron')
-app.on('ready', function () {
+app.whenReady().then(function () {
   const web = webContents.create({})
   new WebContentsView(web)  // eslint-disable-line
 
diff --git a/spec-main/fixtures/api/net-log/main.js b/spec-main/fixtures/api/net-log/main.js
index 040aece614..84b86aafde 100644
--- a/spec-main/fixtures/api/net-log/main.js
+++ b/spec-main/fixtures/api/net-log/main.js
@@ -14,7 +14,7 @@ function request () {
   })
 }
 
-app.on('ready', async () => {
+app.whenReady().then(async () => {
   const netLog = session.defaultSession.netLog
 
   if (process.env.TEST_DUMP_FILE_DYNAMIC) {
diff --git a/spec-main/fixtures/api/test-menu-null/main.js b/spec-main/fixtures/api/test-menu-null/main.js
index f4dd066d67..f0f29ef7e8 100644
--- a/spec-main/fixtures/api/test-menu-null/main.js
+++ b/spec-main/fixtures/api/test-menu-null/main.js
@@ -1,7 +1,7 @@
 const { app, BrowserWindow } = require('electron')
 
 let win
-app.on('ready', function () {
+app.whenReady().then(function () {
   win = new BrowserWindow({})
   win.loadURL('about:blank')
   win.setMenu(null)
diff --git a/spec-main/fixtures/api/test-menu-visibility/main.js b/spec-main/fixtures/api/test-menu-visibility/main.js
index 604dfe1ad9..b550540488 100644
--- a/spec-main/fixtures/api/test-menu-visibility/main.js
+++ b/spec-main/fixtures/api/test-menu-visibility/main.js
@@ -1,7 +1,7 @@
 const { app, BrowserWindow } = require('electron')
 
 let win
-app.on('ready', function () {
+app.whenReady().then(function () {
   win = new BrowserWindow({})
   win.loadURL('about:blank')
   win.setMenuBarVisibility(false)
diff --git a/spec/fixtures/api/command-line/main.js b/spec/fixtures/api/command-line/main.js
index 3a38a2cba2..b5fb791447 100644
--- a/spec/fixtures/api/command-line/main.js
+++ b/spec/fixtures/api/command-line/main.js
@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const payload = {
     hasSwitch: app.commandLine.hasSwitch('foobar'),
     getSwitchValue: app.commandLine.getSwitchValue('foobar')
diff --git a/spec/fixtures/api/cookie-app/main.js b/spec/fixtures/api/cookie-app/main.js
index d3c3dcd467..1b07c84134 100644
--- a/spec/fixtures/api/cookie-app/main.js
+++ b/spec/fixtures/api/cookie-app/main.js
@@ -1,6 +1,6 @@
 const { app, session } = require('electron')
 
-app.on('ready', async function () {
+app.whenReady().then(async function () {
   const url = 'http://foo.bar'
   const persistentSession = session.fromPartition('persist:ence-test')
   const name = 'test'
diff --git a/spec/fixtures/api/default-menu/main.js b/spec/fixtures/api/default-menu/main.js
index 786d9ab4b0..5688e5b458 100644
--- a/spec/fixtures/api/default-menu/main.js
+++ b/spec/fixtures/api/default-menu/main.js
@@ -18,7 +18,7 @@ try {
     Menu.setApplicationMenu(null)
   }
 
-  app.on('ready', () => {
+  app.whenReady().then(() => {
     setImmediate(() => {
       try {
         output(Menu.getApplicationMenu() === expectedMenu)
diff --git a/spec/fixtures/api/exit-closes-all-windows-app/main.js b/spec/fixtures/api/exit-closes-all-windows-app/main.js
index 20d5a1dac2..e61a74dd96 100644
--- a/spec/fixtures/api/exit-closes-all-windows-app/main.js
+++ b/spec/fixtures/api/exit-closes-all-windows-app/main.js
@@ -8,7 +8,7 @@ function createWindow (id) {
   windows.push(window)
 }
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   for (let i = 1; i <= 5; i++) {
     createWindow(i)
   }
diff --git a/spec/fixtures/api/gpu-info.js b/spec/fixtures/api/gpu-info.js
index 1954f9b4b8..15a23f368b 100644
--- a/spec/fixtures/api/gpu-info.js
+++ b/spec/fixtures/api/gpu-info.js
@@ -2,7 +2,7 @@ const { app } = require('electron')
 
 app.commandLine.appendSwitch('--disable-software-rasterizer')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const infoType = process.argv.pop()
   app.getGPUInfo(infoType).then(
     (gpuInfo) => {
diff --git a/spec/fixtures/api/leak-exit-webcontents.js b/spec/fixtures/api/leak-exit-webcontents.js
index f08a8249dd..f2f06c8db6 100644
--- a/spec/fixtures/api/leak-exit-webcontents.js
+++ b/spec/fixtures/api/leak-exit-webcontents.js
@@ -1,5 +1,5 @@
 const { app, webContents } = require('electron')
-app.on('ready', function () {
+app.whenReady().then(function () {
   webContents.create({})
 
   app.quit()
diff --git a/spec/fixtures/api/locale-check/main.js b/spec/fixtures/api/locale-check/main.js
index 47b820c61d..054920c66b 100644
--- a/spec/fixtures/api/locale-check/main.js
+++ b/spec/fixtures/api/locale-check/main.js
@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   process.stdout.write(app.getLocale())
   process.stdout.end()
 
diff --git a/spec/fixtures/api/mixed-sandbox-app/main.js b/spec/fixtures/api/mixed-sandbox-app/main.js
index 0479ca1d77..86cacad01e 100644
--- a/spec/fixtures/api/mixed-sandbox-app/main.js
+++ b/spec/fixtures/api/mixed-sandbox-app/main.js
@@ -12,7 +12,7 @@ if (process.argv.includes('--app-enable-sandbox')) {
 
 let currentWindowSandboxed = false
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   function testWindow (isSandboxed, callback) {
     currentWindowSandboxed = isSandboxed
     const currentWindow = new BrowserWindow({
diff --git a/spec/fixtures/api/quit-app/main.js b/spec/fixtures/api/quit-app/main.js
index 9912071b1f..7f4321aefe 100644
--- a/spec/fixtures/api/quit-app/main.js
+++ b/spec/fixtures/api/quit-app/main.js
@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.on('ready', function () {
+app.whenReady().then(function () {
   // This setImmediate call gets the spec passing on Linux
   setImmediate(function () {
     app.exit(123)
diff --git a/spec/fixtures/api/relaunch/main.js b/spec/fixtures/api/relaunch/main.js
index 69b634f3c2..c149ef78c5 100644
--- a/spec/fixtures/api/relaunch/main.js
+++ b/spec/fixtures/api/relaunch/main.js
@@ -7,7 +7,7 @@ process.on('uncaughtException', () => {
   app.exit(1)
 })
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   const lastArg = process.argv[process.argv.length - 1]
   const client = net.connect(socketPath)
   client.once('connect', () => {
diff --git a/spec/fixtures/api/singleton/main.js b/spec/fixtures/api/singleton/main.js
index 9c1b0a17e4..cdd374bdb6 100644
--- a/spec/fixtures/api/singleton/main.js
+++ b/spec/fixtures/api/singleton/main.js
@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   console.log('started') // ping parent
 })
 
diff --git a/spec/fixtures/api/window-all-closed/main.js b/spec/fixtures/api/window-all-closed/main.js
index 67450d93e7..9e2fcdfa1b 100644
--- a/spec/fixtures/api/window-all-closed/main.js
+++ b/spec/fixtures/api/window-all-closed/main.js
@@ -14,7 +14,7 @@ app.on('quit', () => {
   process.stdout.end()
 })
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const win = new BrowserWindow()
   win.close()
 })
diff --git a/spec/fixtures/no-proprietary-codecs.js b/spec/fixtures/no-proprietary-codecs.js
index 741927b44f..8fc08c4237 100644
--- a/spec/fixtures/no-proprietary-codecs.js
+++ b/spec/fixtures/no-proprietary-codecs.js
@@ -12,7 +12,7 @@ const FIVE_MINUTES = 5 * 60 * 1000
 
 let window
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   window = new BrowserWindow({
     show: false,
     webPreferences: {
diff --git a/spec/fixtures/snapshot-items-available/main.js b/spec/fixtures/snapshot-items-available/main.js
index 601853a294..3604a6bbfa 100644
--- a/spec/fixtures/snapshot-items-available/main.js
+++ b/spec/fixtures/snapshot-items-available/main.js
@@ -2,7 +2,7 @@
 
 const { app } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   let returnCode = 0
   try {
     const testValue = f() // eslint-disable-line no-undef
diff --git a/spec/static/main.js b/spec/static/main.js
index 4c03335805..c08fd5a5f1 100644
--- a/spec/static/main.js
+++ b/spec/static/main.js
@@ -94,7 +94,7 @@ app.on('renderer-process-crashed', (event, contents, killed) => {
   console.log(`webContents ${contents.id} crashed: ${contents.getURL()} (killed=${killed})`)
 })
 
-app.on('ready', async function () {
+app.whenReady().then(async function () {
   await session.defaultSession.clearCache()
   await session.defaultSession.clearStorageData()
   // Test if using protocol module would crash.
diff --git a/spec/ts-smoke/electron/main.ts b/spec/ts-smoke/electron/main.ts
index 08aa6e9825..ea650f2825 100644
--- a/spec/ts-smoke/electron/main.ts
+++ b/spec/ts-smoke/electron/main.ts
@@ -54,7 +54,7 @@ if (!gotLock) {
 
 // This method will be called when Electron has done everything
 // initialization and ready for creating browser windows.
-app.on('ready', () => {
+app.whenReady().then(() => {
   // Create the browser window.
   mainWindow = new BrowserWindow({ width: 800, height: 600 })
 
@@ -147,7 +147,7 @@ app.on('ready', () => {
 
 app.commandLine.appendSwitch('enable-web-bluetooth')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   mainWindow.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
     event.preventDefault()
 
@@ -322,7 +322,7 @@ app.setAboutPanelOptions({
 
 let onlineStatusWindow: Electron.BrowserWindow
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false, vibrancy: 'sidebar' })
   onlineStatusWindow.loadURL(`file://${__dirname}/online-status.html`)
 })
@@ -335,7 +335,7 @@ ipcMain.on('online-status-changed', (event: any, status: any) => {
 // Synopsis
 // https://github.com/atom/electron/blob/master/docs/api/synopsis.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   window = new BrowserWindow({
     width: 800,
     height: 600,
@@ -737,7 +737,7 @@ const template = <Electron.MenuItemConstructorOptions[]> [
 
 menu = Menu.buildFromTemplate(template)
 
-Menu.setApplicationMenu(menu) // Must be called within app.on('ready', function(){ ... });
+Menu.setApplicationMenu(menu) // Must be called within app.whenReady().then(function(){ ... });
 
 Menu.buildFromTemplate([
   { label: '4', id: '4' },
@@ -807,7 +807,7 @@ Menu.buildFromTemplate([
 // net
 // https://github.com/electron/electron/blob/master/docs/api/net.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const request = net.request('https://github.com')
   request.setHeader('Some-Custom-Header-Name', 'Some-Custom-Header-Value')
   const header = request.getHeader('Some-Custom-Header-Name')
@@ -852,7 +852,7 @@ app.on('ready', () => {
 // power-monitor
 // https://github.com/atom/electron/blob/master/docs/api/power-monitor.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   powerMonitor.on('suspend', () => {
     console.log('The system is going to sleep')
   })
@@ -878,7 +878,7 @@ powerSaveBlocker.stop(id)
 // protocol
 // https://github.com/atom/electron/blob/master/docs/api/protocol.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   protocol.registerSchemesAsPrivileged([{ scheme: 'https', privileges: { standard: true, allowServiceWorkers: true } }])
 
   protocol.registerFileProtocol('atom', (request, callback) => {
@@ -910,7 +910,7 @@ app.on('ready', () => {
 // https://github.com/atom/electron/blob/master/docs/api/tray.md
 
 let appIcon: Electron.Tray = null
-app.on('ready', () => {
+app.whenReady().then(() => {
   appIcon = new Tray('/path/to/my/icon')
   const contextMenu = Menu.buildFromTemplate([
     { label: 'Item1', type: 'radio' },
@@ -1016,12 +1016,12 @@ process.setFdLimit(8192)
 // screen
 // https://github.com/atom/electron/blob/master/docs/api/screen.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const size = screen.getPrimaryDisplay().workAreaSize
   mainWindow = new BrowserWindow({ width: size.width, height: size.height })
 })
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const displays = screen.getAllDisplays()
   let externalDisplay: any = null
   for (const i in displays) {
@@ -1190,7 +1190,7 @@ session.defaultSession.webRequest.onBeforeSendHeaders(filter, function (details:
   callback({ cancel: false, requestHeaders: details.requestHeaders })
 })
 
-app.on('ready', function () {
+app.whenReady().then(function () {
   const protocol = session.defaultSession.protocol
   protocol.registerFileProtocol('atom', function (request, callback) {
     const url = request.url.substr(7)
diff --git a/spec/ts-smoke/electron/renderer.ts b/spec/ts-smoke/electron/renderer.ts
index 6db3df7590..ab2fa43b34 100644
--- a/spec/ts-smoke/electron/renderer.ts
+++ b/spec/ts-smoke/electron/renderer.ts
@@ -191,12 +191,12 @@ const app = remote.app
 
 let mainWindow: Electron.BrowserWindow = null
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const size = screen.getPrimaryDisplay().workAreaSize
   mainWindow = new BrowserWindow({ width: size.width, height: size.height })
 })
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const displays = screen.getAllDisplays()
   let externalDisplay: any = null
   for (const i in displays) {