chore: deprecate shell.openExternalSync (#18179)

docs/api/breaking-changes.md

@@ -6,6 +6,19 @@ Breaking changes will be documented here, and deprecation warnings added to JS c
 
 The `FIXME` string is used in code comments to denote things that should be fixed for future releases. See https://github.com/electron/electron/search?q=fixme
 
+# Planned Breaking API Changes (7.0)
+
+## `shell.openExternalSync(url[, options])`
+
+```js
+// Deprecated
+shell.openExternalSync(url)
+// Replace with
+async function openThing (url) {
+  await shell.openExternal(url)
+}
+```
+
 # Planned Breaking API Changes (6.0)
 
 ## `win.setMenu(null)`

docs/api/menu.md

@@ -240,7 +240,10 @@ const template = [
     submenu: [
       {
         label: 'Learn More',
-        click () { require('electron').shell.openExternalSync('https://electronjs.org') }
+        click: async () => {
+          const { shell } = require('electron')
+          await shell.openExternal('https://electronjs.org')
+        }
       }
     ]
   }

docs/api/shell.md

@@ -44,6 +44,8 @@ Returns `Boolean` - Whether an application was available to open the URL.
 
 Open the given external protocol URL in the desktop's default manner. (For example, mailto: URLs in the user's default mail agent).
 
+**Deprecated**
+
 ### `shell.openExternal(url[, options])`
 
 * `url` String - Max 2081 characters on windows.

docs/api/webview-tag.md

@@ -821,10 +821,10 @@ The following example code opens the new url in system's default browser.
 const { shell } = require('electron')
 const webview = document.querySelector('webview')
 
-webview.addEventListener('new-window', (e) => {
+webview.addEventListener('new-window', async (e) => {
   const protocol = require('url').parse(e.url).protocol
   if (protocol === 'http:' || protocol === 'https:') {
-    shell.openExternalSync(e.url)
+    await shell.openExternal(e.url)
   }
 })
 ```

docs/tutorial/security.md

@@ -681,12 +681,12 @@ windows, limiting it to only what you need.
 const { shell } = require('electron')
 
 app.on('web-contents-created', (event, contents) => {
-  contents.on('new-window', (event, navigationUrl) => {
+  contents.on('new-window', async (event, navigationUrl) => {
     // In this example, we'll ask the operating system
     // to open this event's url in the default browser.
     event.preventDefault()
 
-    shell.openExternalSync(navigationUrl)
+    await shell.openExternal(navigationUrl)
   })
 })
 ```

lib/browser/default-menu.ts

@@ -12,28 +12,28 @@ export const setDefaultApplicationMenu = () => {
     submenu: [
       {
         label: 'Learn More',
-        click () {
-          shell.openExternalSync('https://electronjs.org')
+        click: async () => {
+          await shell.openExternal('https://electronjs.org')
         }
       },
       {
         label: 'Documentation',
-        click () {
-          shell.openExternalSync(
+        click: async () => {
+          await shell.openExternal(
             `https://github.com/electron/electron/tree/v${process.versions.electron}/docs#readme`
           )
         }
       },
       {
         label: 'Community Discussions',
-        click () {
-          shell.openExternalSync('https://discuss.atom.io/c/electron')
+        click: async () => {
+          await shell.openExternal('https://discuss.atom.io/c/electron')
         }
       },
       {
         label: 'Search Issues',
-        click () {
-          shell.openExternalSync('https://github.com/electron/electron/issues')
+        click: async () => {
+          await shell.openExternal('https://github.com/electron/electron/issues')
         }
       }
     ]