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

@@ -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.

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(() => {
   })
 }
 ```

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
 })
 ```

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: ['*']

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')

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()

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) => {

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')
   })

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)
 

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)
 

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

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,

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

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

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')
 })

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',

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' },

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', () => {

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')
 })

docs/fiddles/communication/two-processes/asynchronous-messages/main.js

@@ -20,7 +20,7 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
 

docs/fiddles/communication/two-processes/synchronous-messages/main.js

@@ -20,7 +20,7 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })
 

docs/fiddles/media/screenshot/take-screenshot/main.js

@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })

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)

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 () {

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 () {

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 () {

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 () {

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 () {

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 () {

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()
 })

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 () {

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()
 })

docs/fiddles/native-ui/notifications/basic-notification/main.js

@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })

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 () {

docs/fiddles/native-ui/notifications/notification-with-image/main.js

@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })

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 () {

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')
 

docs/fiddles/system/clipboard/copy/main.js

@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })

docs/fiddles/system/clipboard/paste/main.js

@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })

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 () {

docs/fiddles/system/system-information/get-version-information/main.js

@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })

docs/fiddles/windows/manage-windows/create-frameless-window/main.js

@@ -20,6 +20,6 @@ function createWindow () {
   })
 }
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   createWindow()
 })

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 () {

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 () {

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 () {

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 () {

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', () => {

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')
   })

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

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`)
 })

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()
 })

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,