diff --git a/docs/api/accelerator.md b/docs/api/accelerator.md
index 7bbccd4bc54e..8a5b1c92e377 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 67167fd18e9f..7c701add7a45 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 2a8696160976..f836ac5548a7 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 f44e474f146b..11c4213f841b 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 3d18a39f5cde..78263901761d 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 0994416c2a80..2371b8f580d2 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 f4b434f3737b..43ebc3e0cd3a 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 a2bf7eb3035d..eadcd5e7295e 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 45a96f4511da..536e77051a22 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 5da297c3c24a..b93b0b6a4946 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 e49e738ffb17..75c5c13a5609 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 6fb46d31ffa3..414a308da6da 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 290a4a690d63..0fbfa00cbe30 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 22af38488b31..3cc8ff5b63e9 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 8b3ea5609475..6ee64e676234 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 28194d67c02b..5764ebc6a8bc 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 794d5fdcf553..98e6d5ac8977 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 f0496ee77b66..45316522fc62 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 0354182a0c13..fae73e3f95eb 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 38dc956f39ee..942f7022f859 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 70db43febd1a..1adb7c02c9f1 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 37adb5d2b92e..a08035b3355a 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 ad18f25f592f..38774c6374ea 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 b2c4d55901c4..5c8a725c4b66 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 7b46005e85c2..5add46041e18 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 30a360fd879e..d69953df67ce 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 12b5909a36ed..bb6b83cc19b0 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 3ed95a8c3216..9825acbad53e 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 be3dcf9ec3d0..ef865e22b68b 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 2061823025e8..8c60edf69f8b 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 4fff6140a0a2..7f599a744c60 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 c78f16abc859..9246b95bb242 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 78603a253c96..b05ea9cbcc6e 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 4fff6140a0a2..7f599a744c60 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 997426d5920b..40c6001a99ec 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 14a6f96249ff..f723e388fceb 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 2577553e954e..8fbaabcc5b85 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 ac2cc27208dd..36ad14197f6b 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 263c4c5c50ca..b0883e6f4e56 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 f52b46b4dd3f..ef56ec271098 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 1f9f91774ce0..daf87d0fda97 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 e6183c5ff5bd..355f3591f8eb 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 4fff6140a0a2..7f599a744c60 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 4fff6140a0a2..7f599a744c60 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 1297177f2dee..2bb580355e01 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 4fff6140a0a2..7f599a744c60 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 06a25d5ef90a..ddadc5876659 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 cc3736a7df09..b61a4607714e 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 a991395c025f..74bfff02be46 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 ae5d5d07ac33..eb36ac18ce82 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 cbae6beb421c..4be302563411 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 d432785bdc5e..350eeb65b83b 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 c9e003517813..8eecd67b46d5 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 8b9c26334764..2bb9c4e5f5ec 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 9d35e5b8953b..b23677be3735 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 afb459f74f5c..52d71d222817 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 8e5d5d2eb5a6..8b172555b2e3 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 cec51aeef276..74b854c34f40 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 040aece614dc..84b86aafde4c 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 f4dd066d6725..f0f29ef7e8cb 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 604dfe1ad91b..b550540488dd 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 3a38a2cba256..b5fb79144770 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 d3c3dcd467c1..1b07c841349a 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 786d9ab4b0d3..5688e5b45845 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 20d5a1dac2a1..e61a74dd9612 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 1954f9b4b8a8..15a23f368b1d 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 f08a8249dde8..f2f06c8db600 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 47b820c61ddd..054920c66b2f 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 0479ca1d7704..86cacad01e13 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 9912071b1f36..7f4321aefe89 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 69b634f3c2a0..c149ef78c563 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 9c1b0a17e4cf..cdd374bdb6a8 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 67450d93e751..9e2fcdfa1bb7 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 741927b44f27..8fc08c423770 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 601853a29477..3604a6bbfaf2 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 4c033358059c..c08fd5a5f1f0 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 08aa6e9825e1..ea650f28255d 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 6db3df75908b..ab2fa43b3433 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) {