Skip to main content

Breaking Changes

Breaking-Änderungen werden hier dokumentiert, und Veraltungswarnungen werden js-Code nach Möglichkeit hinzugefügt, mindestens eine Hauptversion, bevor die Änderung vorgenommen wird.

Typen von Breaking-Änderungen

In diesem Dokument wird die folgende Konvention zur Kategorisierung von Breaking-Änderungen verwendet:

  • API geändert: Die API wurde so geändert, dass Code, der nicht aktualisiert wurde, garantiert eine Ausnahme wirft.
  • Verhalten geändert: Das Verhalten von Electron hat sich geändert, aber nicht so, dass eine Ausnahme unbedingt geworfen wird.
  • Standard geändert: Code, der vom alten Standardwert abhängig ist, funktioniert möglicherweise nicht mehr und wirft nicht notwendigerweise eine Ausnahme. Das alte Verhalten kann durch explizite Angabe des Wertes wiederhergestellt werden.
  • Veraltet: Eine API wurde als veraltet markiert. Die API wird weiterhin funktionieren, sendet aber eine Veraltungswarnung aus und wird in einer zukünftigen Version entfernt.
  • Entfernt: Eine API oder Funktion wurde entfernt und wird von Electron nicht mehr unterstützt.

Geplante Bruch-API-Änderungen (17.0)

Removed: desktopCapturer.getSources in the renderer

The desktopCapturer.getSources API is now only available in the main process. This has been changed in order to improve the default security of Electron apps.

If you need this functionality, it can be replaced as follows:

// Main process
const { ipcMain, desktopCapturer } = require('electron')

ipcMain.handle(
'DESKTOP_CAPTURER_GET_SOURCES',
(event, opts) => desktopCapturer.getSources(opts)
)
// Renderer process
const { ipcRenderer } = require('electron')

const desktopCapturer = {
getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
}

However, you should consider further restricting the information returned to the renderer; for instance, displaying a source selector to the user and only returning the selected source.

Geplante Bruch-API-Änderungen (16.0)

Behavior Changed: crashReporter implementation switched to Crashpad on Linux

The underlying implementation of the crashReporter API on Linux has changed from Breakpad to Crashpad, bringing it in line with Windows and Mac. As a result of this, child processes are now automatically monitored, and calling process.crashReporter.start in Node child processes is no longer needed (and is not advisable, as it will start a second instance of the Crashpad reporter).

There are also some subtle changes to how annotations will be reported on Linux, including that long values will no longer be split between annotations appended with __1, __2 and so on, and instead will be truncated at the (new, longer) annotation value limit.

Deprecated: desktopCapturer.getSources in the renderer

Usage of the desktopCapturer.getSources API in the renderer has been deprecated and will be removed. This change improves the default security of Electron apps.

See here for details on how to replace this API in your app.

Geplante Bruch-API-Änderungen (15.0)

Standardwert geändert: nativeWindowOpen ist standardmäßig auf true eingestellt

Prior to Electron 15, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.

See the documentation for window.open in Electron for more details.

Geplante Bruch-API-Änderungen (14.0)

Removed: remote module

The remote module was deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.

// Deprecated in Electron 12:
const { BrowserWindow } = require('electron').remote
// Replace with:
const { BrowserWindow } = require('@electron/remote')

// In the main process:
require('@electron/remote/main').initialize()

Entfernt: app.allowRendererProcessReuse

The app.allowRendererProcessReuse property will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.

Weitere Informationen findest du unter #18397.

Entfernt: Browserfenster-Affinität

Die Einstellung Affinität beim Erstellen eines neuen BrowserWindow wird entfernt als Teil unseres Plans, sich stärker an das Prozessmodell von Chromium für Sicherheit, Leistung und Wartbarkeit anzupassen.

Weitere Informationen findest du unter #18397.

API geändert: window.open()

Der optionale Parameter FrameName legt nicht mehr den Titel des Fensters fest. Dies folgt nun der Spezifikation, die in der nativen Dokumentation unter dem zugehörigen Parameter windowName beschrieben wird.

Wenn Sie diesen Parameter verwenden, um den Titel eines Fensters festzulegen, können Sie stattdessen win.setTitle(title) verwenden.

Entfernt: worldSafeExecuteJavaScript

In Electron 14 wird worldSafeExecuteJavaScript entfernt. Es gibt keine Alternative, bitte stelle sicher, dass dein Code mit dieser Eigenschaft funktioniert. Es wurde standardmäßig aktiviert, da Electron 12.

Sie werden von dieser Änderung betroffen sein, wenn Sie entweder webFrame.executeJavaScript oder webFrame.executeJavaScriptInIsolatedWorld verwenden. Sie müssen sicherstellen, dass die von einer dieser Methoden zurückgegebenen Werte von der Context Bridge API unterstützt werden, da diese Methoden denselben Wert verwenden, der die Semantik übergeht.

Removed: BrowserWindowConstructorOptions inheriting from parent windows

Prior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.

Instead, explicitly set options for the new window with setWindowOpenHandler:

webContents.setWindowOpenHandler((details) => {
return {
action: 'allow',
overrideBrowserWindowOptions: {
// ...
}
}
})

Entfernt: additionalFeatures

The deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.

// Removed in Electron 14
// Triggered by window.open('...', '', 'my-key')
webContents.on('did-create-window', (window, details) => {
if (details.additionalFeatures.includes('my-key')) {
// ...
}
})

// Replace with
webContents.on('did-create-window', (window, details) => {
if (details.options['my-key']) {
// ...
}
})

Geplante Bruch-API-Änderungen (13.0)

API geändert: session.setPermissionCheckHandler(handler)

Die Handler Methoden ersten Parameters waren zuvor immer ein webContents, es kann jetzt manchmal null sein. Sie sollten die requestingOrigin, einbettenOrigin und securityOrigin Eigenschaften verwenden, um auf die Berechtigungsprüfung korrekt zu reagieren. Da der Webcontent null sein kann nicht mehr auf ihn angewiesen werden.

// Alter Code
session.setPermissionCheckHandler((webContents, permission) => {
if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
return true
}
return false
})

// Ersetzen mit
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
return true
}
return false
})

Entfernt: shell.moveItemToTrash()

Die veraltete synchrone shell.moveItemToTrash() API wurde entfernt. Verwende stattdessen die asynchrone shell.trashItem().

// Entfernt in Electron 13
shell.moveItemTosh(path)
// Ersetzen durch
shell.trashItem(path).then(/* ... */)

Entfernt: BrowserWindow Erweiterungs-APIs

Die veralteten Erweiterungs-APIs wurden entfernt:

  • BrowserWindow.addExtension(path)
  • BrowserWindow.addDevToolsExtension(path)
  • BrowserWindow.removeExtension(name)
  • BrowserWindow.removeDevToolsExtension(name)
  • BrowserWindow.getExtensions()
  • BrowserWindow.getDevToolsExtensions()

Use the session APIs instead:

  • ses.loadExtension(path)
  • ses.removeExtension(extension_id)
  • ses.getAllExtensions()
// In Electron 13 entfernt
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Ersetzen durch
session.defaultSession.loadExtension(path)
// In Electron 13 entfernt
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Ersetzen durch
session.defaultSession.loadExtension(path)
// In Electron 13 entfernt
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Ersetzen durch
session.defaultSession.getAllExtensions()

Eliminado: métodos en systemPreferences

Die folgenden systemPreferences Methoden wurden veraltet:

  • systemPreferences.isDarkMode()
  • systemPreferences.isInvertedColorScheme()
  • systemPreferences.isHighContrastColorScheme()

Verwende stattdessen die folgenden nativeTheme Eigenschaften:

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
// Entfernt in Electron 13
systemPreferences.isDarkMode()
// Ersetzen durch
nativeTheme.shouldUseDarkColors

// Entfernt in Electron 13
systemPreferences. sInvertedColorScheme()
// Ersetzen durch
nativeTheme.shouldUseInvertedColorScheme

// In Electron 13 entfernt
systemPreferences.isHighContrastColorScheme()
// Ersetzen durch
nativeTheme.shouldUseHighContrastColorColorScheme

Veraltet: WebContents new-window Ereignis

Das new-window Ereignis von WebContents wurde veraltet. It is replaced by webContents.setWindowOpenHandler().

// Veraltet in Electron 13
webContents.on('new-window', (event) => {
event. reventDefault()
})

// Ersetzen durch
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})

Geplante Bruch-API-Änderungen (12.0)

Entfernt: Pepper Flash Unterstützung

Chromium hat die Unterstützung für Flash entfernt, und deshalb müssen wir diesem Beispiel folgen. Weitere Details findest du in der Flash-Roadmap von Chromium.

Standardwert geändert: worldSafeExecuteJavaScript ist standardmäßig auf true eingestellt

In Electron 12, worldSafeExecuteJavaScript wird standardmäßig aktiviert. Um das vorherige Verhalten wiederherzustellen, muss worldSafeExecuteJavaScript: false in WebPreferences angegeben werden. Bitte beachte, dass die Einstellung dieser Option auf false unsicher ist.

Diese Einstellung wird in Electron 14 entfernt, also migriere bitte deinen Code um den Standardwert zu unterstützen.

Standardwert geändert: contextIsolation ist standardmäßig auf true eingestellt

In Electron 12, contextIsolation wird standardmäßig aktiviert. Um das vorherige Verhalten wiederherzustellen, muss contextIsolation: false in WebPreferences angegeben werden.

We recommend having contextIsolation enabled for the security of your application.

Another implication is that require() cannot be used in the renderer process unless nodeIntegration is true and contextIsolation is false.

For more details see: https://github.com/electron/electron/issues/23506

Entfernt: crashReporter.getCrashesDirectory()

The crashReporter.getCrashesDirectory method has been removed. Usage should be replaced by app.getPath('crashDumps').

// Removed in Electron 12
crashReporter.getCrashesDirectory()
// Replace with
app.getPath('crashDumps')

Removed: crashReporter methods in the renderer process

The following crashReporter methods are no longer available in the renderer process:

  • crashReporter.start
  • crashReporter.getLastCrashReport
  • crashReporter.getUploadedReports
  • crashReporter.getUploadToServer
  • crashReporter.setUploadToServer
  • crashReporter.getCrashesDirectory

They should be called only from the main process.

See #23265 for more details.

Default Changed: crashReporter.start({ compress: true })

The default value of the compress option to crashReporter.start has changed from false to true. This means that crash dumps will be uploaded to the crash ingestion server with the Content-Encoding: gzip header, and the body will be compressed.

If your crash ingestion server does not support compressed payloads, you can turn off compression by specifying { compress: false } in the crash reporter options.

Deprecated: remote module

The remote module is deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.

// Deprecated in Electron 12:
const { BrowserWindow } = require('electron').remote
// Replace with:
const { BrowserWindow } = require('@electron/remote')

// In the main process:
require('@electron/remote/main').initialize()

Deprecated: shell.moveItemToTrash()

The synchronous shell.moveItemToTrash() has been replaced by the new, asynchronous shell.trashItem().

// Deprecated in Electron 12
shell.moveItemToTrash(path)
// Replace with
shell.trashItem(path).then(/* ... */)

Geplante Bruch-API-Änderungen (11.0)

Removed: BrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserView

The experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews} have now been removed. Additionally, the id property of BrowserView has also been removed.

For more detailed information, see #23578.

Geplante Bruch-API-Änderungen (10.0)

Veraltet: companyName Argument, um crashReporter.start()

The companyName argument to crashReporter.start(), which was previously required, is now optional, and further, is deprecated. Um das gleiche Verhalten auf nicht veraltete Weise zu erhalten, können Sie einen companyName Wert in globalExtraübergeben.

// Deprecated in Electron 10
crashReporter.start({ companyName: 'Umbrella Corporation' })
// Replace with
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })

Deprecated: crashReporter.getCrashesDirectory()

The crashReporter.getCrashesDirectory method has been deprecated. Usage should be replaced by app.getPath('crashDumps').

// Deprecated in Electron 10
crashReporter.getCrashesDirectory()
// Replace with
app.getPath('crashDumps')

Deprecated: crashReporter methods in the renderer process

Calling the following crashReporter methods from the renderer process is deprecated:

  • crashReporter.start
  • crashReporter.getLastCrashReport
  • crashReporter.getUploadedReports
  • crashReporter.getUploadToServer
  • crashReporter.setUploadToServer
  • crashReporter.getCrashesDirectory

The only non-deprecated methods remaining in the crashReporter module in the renderer are addExtraParameter, removeExtraParameter and getParameters.

All above methods remain non-deprecated when called from the main process.

See #23265 for more details.

Deprecated: crashReporter.start({ compress: false })

Setting { compress: false } in crashReporter.start is deprecated. Nearly all crash ingestion servers support gzip compression. This option will be removed in a future version of Electron.

Standardwert geändert: enableRemoteModule ist standardmäßig auf false eingestellt

In Electron 9, using the remote module without explicitly enabling it via the enableRemoteModule WebPreferences option began emitting a warning. In Electron 10, the remote module is now disabled by default. To use the remote module, enableRemoteModule: true must be specified in WebPreferences:

const w = new BrowserWindow({
webPreferences: {
enableRemoteModule: true
}
})

We recommend moving away from the remote module.

protocol.unregisterProtocol

protocol.uninterceptProtocol

Diese Schnittstelle ist jetzt Synchron und der optionale callback wird nicht länger gebraucht.

// Deprecated
protocol.unregisterProtocol(scheme, () => { /* ... */ })
// Replace with
protocol.unregisterProtocol(scheme)

protocol.registerFileProtocol

protocol.registerBufferProtocol

protocol.registerStringProtocol

protocol.registerHttpProtocol

protocol.registerStreamProtocol

protocol.interceptFileProtocol

protocol.interceptStringProtocol

protocol.interceptBufferProtocol

protocol.interceptHttpProtocol

protocol.interceptStreamProtocol

Diese Schnittstelle ist jetzt Synchron und der optionale callback wird nicht länger gebraucht.

// Deprecated
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// Replace with
protocol.registerFileProtocol(scheme, handler)

Das registrierte oder abgefangene Protokoll hat keine Auswirkungen auf die aktuelle Seite, bis eine Navigation stattfindet.

protocol.isProtocolHandled

Diese Schnittstelle ist veraltet anstatt dessen sollten Benutzer protocol.isProtocolRegistered und protocol.isProtocolIntercepted nutzen.

// Deprecated
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// Replace with
const isRegistered = protocol.isProtocolRegistered(scheme)
const isIntercepted = protocol.isProtocolIntercepted(scheme)

Geplante Bruch-API-Änderungen (9.0)

Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default

As of Electron 9 we do not allow loading of non-context-aware native modules in the renderer process. This is to improve security, performance and maintainability of Electron as a project.

If this impacts you, you can temporarily set app.allowRendererProcessReuse to false to revert to the old behavior. This flag will only be an option until Electron 11 so you should plan to update your native modules to be context aware.

Weitere Informationen findest du unter #18397.

Deprecated: BrowserWindow extension APIs

The following extension APIs have been deprecated:

  • BrowserWindow.addExtension(path)
  • BrowserWindow.addDevToolsExtension(path)
  • BrowserWindow.removeExtension(name)
  • BrowserWindow.removeDevToolsExtension(name)
  • BrowserWindow.getExtensions()
  • BrowserWindow.getDevToolsExtensions()

Use the session APIs instead:

  • ses.loadExtension(path)
  • ses.removeExtension(extension_id)
  • ses.getAllExtensions()
// Deprecated in Electron 9
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)
// Deprecated in Electron 9
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)
// Deprecated in Electron 9
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()

Removed: <webview>.getWebContents()

Diese API, die seit Electron 8.0 veraltet ist, wird nun entfernt.

// Removed in Electron 9.0
webview.getWebContents()
// Replace with
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())

Entfernt: webFrame.setLayoutZoomLevelLimits()

Chromium hat die Unterstützung für das Ändern des Layout-Zoomniveaus entfernt und es übersteigt die Möglichkeiten von uns, dies zu pflegen. The function was deprecated in Electron 8.x, and has been removed in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.

Behavior Changed: Sending non-JS objects over IPC now throws an exception

In Electron 8.0, IPC was changed to use the Structured Clone Algorithm, bringing significant performance improvements. To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren't serializable with Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Whenever the old algorithm was invoked, a deprecation warning was printed.

In Electron 9.0, the old serialization algorithm has been removed, and sending such non-serializable objects will now throw an "object could not be cloned" error.

API Changed: shell.openItem is now shell.openPath

The shell.openItem API has been replaced with an asynchronous shell.openPath API. You can see the original API proposal and reasoning here.

Geplante Bruch-API-Änderungen (8.0)

Behavior Changed: Values sent over IPC are now serialized with Structured Clone Algorithm

The algorithm used to serialize objects sent over IPC (through ipcRenderer.send, ipcRenderer.sendSync, WebContents.send and related methods) has been switched from a custom algorithm to V8's built-in Structured Clone Algorithm, the same algorithm used to serialize messages for postMessage. This brings about a 2x performance improvement for large messages, but also brings some breaking changes in behavior.

  • Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any such values, over IPC will now throw an exception, instead of silently converting the functions to undefined.
// Previously:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => results in { value: 3 } arriving in the main process

// From Electron 8:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => throws Error("() => {} could not be cloned.")
  • NaN, Infinity and -Infinity will now be correctly serialized, instead of being converted to null.
  • Objects containing cyclic references will now be correctly serialized, instead of being converted to null.
  • Set, Map, Error and RegExp values will be correctly serialized, instead of being converted to {}.
  • BigInt values will be correctly serialized, instead of being converted to null.
  • Sparse arrays will be serialized as such, instead of being converted to dense arrays with nulls.
  • Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.
  • Typed Arrays (such as Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.
  • Node.js Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:
Buffer.from(value.buffer, value.byteOffset, value.byteLength)

Sending any objects that aren't native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a 'could not be cloned' error.

Deprecated: <webview>.getWebContents()

This API is implemented using the remote module, which has both performance and security implications. Therefore its usage should be explicit.

// Deprecated
webview.getWebContents()
// Replace with
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())

However, it is recommended to avoid using the remote module altogether.

// main
const { ipcMain, webContents } = require('electron')

const getGuestForWebContents = (webContentsId, contents) => {
const guest = webContents.fromId(webContentsId)
if (!guest) {
throw new Error(`Invalid webContentsId: ${webContentsId}`)
}
if (guest.hostWebContents !== contents) {
throw new Error('Access denied to webContents')
}
return guest
}

ipcMain.handle('openDevTools', (event, webContentsId) => {
const guest = getGuestForWebContents(webContentsId, event.sender)
guest.openDevTools()
})

// renderer
const { ipcRenderer } = require('electron')

ipcRenderer.invoke('openDevTools', webview.getWebContentsId())

Deprecated: webFrame.setLayoutZoomLevelLimits()

Chromium hat die Unterstützung für das Ändern des Layout-Zoomniveaus entfernt und es übersteigt die Möglichkeiten von uns, dies zu pflegen. The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.

Deprecated events in systemPreferences

The following systemPreferences events have been deprecated:

  • inverted-color-scheme-changed
  • high-contrast-color-scheme-changed

Use the new updated event on the nativeTheme module instead.

// Deprecated
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })

// Replace with
nativeTheme.on('updated', () => { /* ... */ })

Deprecated: methods in systemPreferences

Die folgenden systemPreferences Methoden wurden veraltet:

  • systemPreferences.isDarkMode()
  • systemPreferences.isInvertedColorScheme()
  • systemPreferences.isHighContrastColorScheme()

Verwende stattdessen die folgenden nativeTheme Eigenschaften:

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
// Deprecated
systemPreferences.isDarkMode()
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.isInvertedColorScheme()
// Replace with
nativeTheme.shouldUseInvertedColorScheme

// Deprecated
systemPreferences.isHighContrastColorScheme()
// Replace with
nativeTheme.shouldUseHighContrastColors

Planned Breaking API Changes (7.0)

Deprecated: Atom.io Node Headers URL

This is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules. Both will be supported for the foreseeable future but it is recommended that you switch.

Deprecated: https://atom.io/download/electron

Replace with: https://electronjs.org/headers

API Changed: session.clearAuthCache() no longer accepts options

The session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.

// Deprecated
session.clearAuthCache({ type: 'password' })
// Replace with
session.clearAuthCache()

API Changed: powerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState

// Removed in Electron 7.0
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)

API Changed: powerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime

// Removed in Electron 7.0
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()

API Changed: webFrame.setIsolatedWorldInfo replaces separate methods

// Removed in Electron 7.0
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Replace with
webFrame.setIsolatedWorldInfo(
worldId,
{
securityOrigin: 'some_origin',
name: 'human_readable_name',
csp: 'content_security_policy'
})

Removed: marked property on getBlinkMemoryInfo

This property was removed in Chromium 77, and as such is no longer available.

Behavior Changed: webkitdirectory attribute for <input type="file"/> now lists directory contents

The webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder.

As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).

As an illustration, take a folder with this structure:

folder
├── file1
├── file2
└── file3

In Electron <=6, this would return a FileList with a File object for:

path/to/folder

In Electron 7, this now returns a FileList with a File object for:

/path/to/folder/file3
/path/to/folder/file2
/path/to/folder/file1

Note that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).

API Changed: Callback-based versions of promisified APIs

Electron 5 and Electron 6 introduced Promise-based versions of existing asynchronous APIs and deprecated their older, callback-based counterparts. In Electron 7, all deprecated callback-based APIs are now removed.

These functions now only return Promises:

  • app.getFileIcon() #15742
  • app.dock.show() #16904
  • contentTracing.getCategories() #16583
  • contentTracing.getTraceBufferUsage() #16600
  • contentTracing.startRecording() #16584
  • contentTracing.stopRecording() #16584
  • contents.executeJavaScript() #17312
  • cookies.flushStore() #16464
  • cookies.get() #16464
  • cookies.remove() #16464
  • cookies.set() #16464
  • debugger.sendCommand() #16861
  • dialog.showCertificateTrustDialog() #17181
  • inAppPurchase.getProducts() #17355
  • inAppPurchase.purchaseProduct()#17355
  • netLog.stopLogging() #16862
  • session.clearAuthCache() #17259
  • session.clearCache() #17185
  • session.clearHostResolverCache() #17229
  • session.clearStorageData() #17249
  • session.getBlobData() #17303
  • session.getCacheSize() #17185
  • session.resolveProxy() #17222
  • session.setProxy() #17222
  • shell.openExternal() #16176
  • webContents.loadFile() #15855
  • webContents.loadURL() #15855
  • webContents.hasServiceWorker() #16535
  • webContents.printToPDF() #16795
  • webContents.savePage() #16742
  • webFrame.executeJavaScript() #17312
  • webFrame.executeJavaScriptInIsolatedWorld() #17312
  • webviewTag.executeJavaScript() #17312
  • win.capturePage() #15743

These functions now have two forms, synchronous and Promise-based asynchronous:

  • dialog.showMessageBox()/dialog.showMessageBoxSync() #17298
  • dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973
  • dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054

Planned Breaking API Changes (6.0)

API Changed: win.setMenu(null) is now win.removeMenu()

// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()

API Changed: electron.screen in the renderer process should be accessed via remote

// Deprecated
require('electron').screen
// Replace with
require('electron').remote.screen

API Changed: require()ing node builtins in sandboxed renderers no longer implicitly loads the remote version

// Deprecated
require('child_process')
// Replace with
require('electron').remote.require('child_process')

// Deprecated
require('fs')
// Replace with
require('electron').remote.require('fs')

// Deprecated
require('os')
// Replace with
require('electron').remote.require('os')

// Deprecated
require('path')
// Replace with
require('electron').remote.require('path')

Deprecated: powerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState

// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)

Deprecated: powerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime

// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()

Deprecated: app.enableMixedSandbox() is no longer needed

// Deprecated
app.enableMixedSandbox()

Mixed-sandbox mode is now enabled by default.

Deprecated: Tray.setHighlightMode

Under macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.

// Deprecated
tray.setHighlightMode(mode)
// API will be removed in v7.0 without replacement.

Planned Breaking API Changes (5.0)

Default Changed: nodeIntegration and webviewTag default to false, contextIsolation defaults to true

The following webPreferences option default values are deprecated in favor of the new defaults listed below.

PropertyDeprecated DefaultNew Default
contextIsolationfalsetrue
nodeIntegrationtruefalse
webviewTagnodeIntegration if set else truefalse

z.B. Re-enabling the webviewTag

const w = new BrowserWindow({
webPreferences: {
webviewTag: true
}
})

Behavior Changed: nodeIntegration in child windows opened via nativeWindowOpen

Child windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.

API Changed: Registering privileged schemes must now be done before app ready

Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. A new API, protocol.registerSchemesAsPrivileged has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.

Deprecated: webFrame.setIsolatedWorld* replaced with webFrame.setIsolatedWorldInfo

// Deprecated
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Replace with
webFrame.setIsolatedWorldInfo(
worldId,
{
securityOrigin: 'some_origin',
name: 'human_readable_name',
csp: 'content_security_policy'
})

API Changed: webFrame.setSpellCheckProvider now takes an asynchronous callback

The spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.

// Deprecated
webFrame.setSpellCheckProvider('en-US', true, {
spellCheck: (text) => {
return !spellchecker.isMisspelled(text)
}
})
// Replace with
webFrame.setSpellCheckProvider('en-US', {
spellCheck: (words, callback) => {
callback(words.filter(text => spellchecker.isMisspelled(text)))
}
})

API Changed: webContents.getZoomLevel and webContents.getZoomFactor are now synchronous

webContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters, instead directly returning their number values.

// Deprecated
webContents.getZoomLevel((level) => {
console.log(level)
})
// Replace with
const level = webContents.getZoomLevel()
console.log(level)
// Deprecated
webContents.getZoomFactor((factor) => {
console.log(factor)
})
// Replace with
const factor = webContents.getZoomFactor()
console.log(factor)

Planned Breaking API Changes (4.0)

The following list includes the breaking API changes made in Electron 4.0.

app.makeSingleInstance

// Deprecated
app.makeSingleInstance((argv, cwd) => {
/* ... */
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
/* ... */
})

app.releaseSingleInstance

// Veraltet
app.releaseSingleInstance()
// Ersetze mit
app.releaseSingleInstanceLock()

app.getGPUInfo

app.getGPUInfo('complete')
// Verhält sich jetzt gleich wie `basic` auf macOS
app.getGPUInfo('basic')

win_delay_load_hook

When building native modules for windows, the win_delay_load_hook variable in the module's binding.gyp must be true (which is the default). If this hook is not present, then the native module will fail to load on Windows, with an error message like Cannot find module. See the native module guide for more.

Breaking API Changes (3.0)

The following list includes the breaking API changes in Electron 3.0.

app

// Veraltet
app.getAppMemoryInfo()
// Ersetze mit
app.getAppMetrics()

// Veraltet
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // Deprecated property

Browserfenster

// Deprecated
const optionsA = { webPreferences: { blinkFeatures: '' } }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
const windowB = new BrowserWindow(optionsB)

// Deprecated
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play_pause') {
// do something
}
})
// Replace with
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play-pause') {
// do something
}
})

clipboard

// Veraltet
clipboard.readRtf()
// Ersetze mit
clipboard.readRTF()

// Veraltet
clipboard.writeRtf()
// Ersetze mit
clipboard.writeRTF()

// Veraltet
clipboard.readHtml()
// Ersetze mit
clipboard.readHTML()

// Veraltet
clipboard.writeHtml()
// Ersetze mit
clipboard.writeHTML()

crashReporter

// Veraltet
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
autoSubmit: true
})
// Ersetze mit
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
uploadToServer: true
})

nativeImage

// Veraltet
nativeImage.createFromBuffer(buffer, 1.0)
// Ersetze mit
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})

process

// Veraltet
const info = process.getProcessMemoryInfo()

screen

// Veraltet
screen.getMenuBarHeight()
// Ersetze mit
screen.getPrimaryDisplay().workArea

session

// Deprecated
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
callback(true)
})
// Replace with
ses.setCertificateVerifyProc((request, callback) => {
callback(0)
})

Fach

// Veraltet
tray.setHighlightMode(true)
// Ersetze mit
tray.setHighlightMode('on')

// Veraltet
tray.setHighlightMode(false)
// Ersetze mit
tray.setHighlightMode('off')

webContents

// Veraltet
webContents.openDevTools({ detach: true })
// Ersetze mit
webContents.openDevTools({ mode: 'detach' })

// Entfernt
webContents.setSize(options)
// Für diese API gibt es keinen Ersatz

webFrame

// Veraltet
webFrame.registerURLSchemeAsSecure('app')
// Ersetze mit
protocol.registerStandardSchemes(['app'], { secure: true })

// Veraltet
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// Ersetze mit
protocol.registerStandardSchemes(['app'], { secure: true })

<webview>

// Entfernt
webview.setAttribute('disableguestresize', '')
// Für diese API gibt es keinen Ersatz

// Entfernt
webview.setAttribute('guestinstance', instanceId)
// Für diese API gibt es keinen Ersatz

// Keyboard listener funktionieren nicht länger für webview tag
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }

Node Headers URL

This is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules.

Deprecated: https://atom.io/download/atom-shell

Replace with: https://atom.io/download/electron

Breaking API Changes (2.0)

The following list includes the breaking API changes made in Electron 2.0.

Browserfenster

// Deprecated
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { titleBarStyle: 'hiddenInset' }
const windowB = new BrowserWindow(optionsB)
// Entfernt
menu.popup(browserWindow, 100, 200, 2)
// Ersetze mit
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

nativeImage

// Entfernt
nativeImage.toPng()
// Ersetze mit
nativeImage.toPNG()

// Entfernt
nativeImage.toJpeg()
// Ersetze mit
nativeImage.toJPEG()

process

  • process.versions.electron and process.version.chrome will be made read-only properties for consistency with the other process.versions properties set by Node.

webContents

// Entfernt
webContents.setZoomLevelLimits(1, 2)
// Ersetze mit
webContents.setVisualZoomLevelLimits(1, 2)

webFrame

// Entfernt
webFrame.setZoomLevelLimits(1, 2)
// Ersetze mit
webFrame.setVisualZoomLevelLimits(1, 2)

<webview>

// Entfernt
webview.setZoomLevelLimits(1, 2)
// Ersetze mit
webview.setVisualZoomLevelLimits(1, 2)

Duplicate ARM Assets

Each Electron release includes two identical ARM builds with slightly different filenames, like electron-v1.7.3-linux-arm.zip and electron-v1.7.3-linux-armv7l.zip. The asset with the v7l prefix was added to clarify to users which ARM version it supports, and to disambiguate it from future armv6l and arm64 assets that may be produced.

The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Starting at 2.0, the unprefixed file will no longer be published.

For details, see 6986 and 7189.