Breaking Changes

Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least one major version before the change is made.

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

Entfernt: macOS 12 Unterstützung

macOS 12 (Monterey) is no longer supported by Chromium.

Older versions of Electron will continue to run on Monterey, but macOS 13 (Ventura) or later will be required to run Electron v44.0.0 and higher.

Removed: Windows 32-bit (ia32) and Linux 32-bit ARM (armv7l) support

Electron no longer publishes prebuilt binaries for 32-bit platforms: Windows x86 (win32-ia32) and Linux ARM (linux-armv7l). All related release artifacts (chromedriver, mksnapshot, ffmpeg, and the Windows x86 node.lib on the Electron headers CDN) are no longer published either.

Older versions of Electron will continue to support these platforms, but Electron v44.0.0 and higher will only be published for 64-bit platforms.

Once the v43 series reaches end of life in January 2027, these 32-bit platforms will no longer be supported.

Removed: clipboard module is no longer available in the renderer process

The clipboard module is no longer exposed to renderer processes. It was previously deprecated and is now removed in line with RFC 0019 to close the security risk of granting non-sandboxed renderers direct clipboard access.

Renderers should use the navigator.clipboard API to safely work with the system clipboard. If more advanced usage is necessary, expose the necessary helpers from a preload script using the contextBridge API. When using contextBridge care must be taken to ensure that the clipboard API is not exposed to untrusted content.

Geplante Bruch-API-Änderungen (43.0)

Behavior Changed: Rounded corners on Linux

Frameless windows default to rounded corners on Linux if the desktop environment supports client-side decorations. This can be configured using the existing roundedCorners option on BrowserWindow, which is now supported on Linux and defaults to true on all platforms.

Behavior Changed: WCO respects the native title bar layout on Linux

Frameless windows with Window Controls Overlay (WCO) now adopt the native title bar layout and user settings on Linux. For example, controls will appear on the left side of the frame on RTL systems, and only the close button will be visible by default on GNOME. Depending on the user's desktop environment and configuration, buttons can appear on the left or right side of the frame (or both). To account for all possibilities, use the CSS variables env(titlebar-area-x, 0px) and env(titlebar-area-width, 100%) to constrain your app's title bar content to a safe area.

Behavior Changed: NativeImage.toBitmap() now normalizes color space

NativeImage.toBitmap() (and its deprecated alias NativeImage.getBitmap()) now normalizes pixel data to sRGB by default. Previously, raw pixel data was returned without color space conversion, which meant pixel values from images with different embedded color profiles (e.g., Display P3 on macOS) could differ for the same visual color.

To preserve the previous behavior, pass the image's original color space in the colorSpace option. You can also pass colorSpace to convert to any other specific color space:

const image = nativeImage.createFromPath('photo.png')
// New default: normalized to sRGB
const srgbBitmap = image.toBitmap()
// Convert to Display P3
const p3Bitmap = image.toBitmap({
  colorSpace: {
    primaries: 'p3',
    transfer: 'srgb',
    matrix: 'rgb',
    range: 'full'
  }
})

Behavior Changed: chrome.scripting CSS injection matches more fallback frames

Extensions using chrome.scripting.insertCSS() or chrome.scripting.removeCSS() now follow Chrome's behavior when Electron cannot match a frame's URL directly, such as with about:blank or data: frames. If the extension has access to the page that created the frame, CSS may now be inserted into or removed from those fallback frames as well.

Apps or extensions that relied on Electron skipping those frames should narrow their injection target, frame IDs, or match patterns.

Behavior Changed: Dialog methods default to Downloads directory

The defaultPath option for the following methods now defaults to the user's Downloads folder (or their home directory if Downloads doesn't exist) when not explicitly provided:

• dialog.showOpenDialog
• dialog.showOpenDialogSync
• dialog.showSaveDialog
• dialog.showSaveDialogSync

Previously, when no defaultPath was provided, the underlying OS file dialog would determine the initial directory — typically remembering the last directory the user navigated to, or falling back to an OS-specific default. Now, Electron explicitly sets the initial directory to Downloads, which also means the OS will no longer track and restore the last-used directory between dialog invocations.

To preserve the old behavior, you can track the last-used directory yourself and pass it as defaultPath:

const path = require('node:path')

let lastUsedPath
const result = await dialog.showOpenDialog({
  defaultPath: lastUsedPath
})

if (!result.canceled && result.filePaths.length > 0) {
  lastUsedPath = path.dirname(result.filePaths[0])
}

Removed: showHiddenFiles in Dialogs on Linux

The showHiddenFiles property is no longer supported on Linux. It continues to work on macOS and Windows. GTK intends for this feature to be a user choice rather than an app choice, and has removed the API to do this programmatically.

Geplante Bruch-API-Änderungen (42.0)

Behavior Changed: macOS notifications now use UNNotification API

Electron has migrated from the deprecated NSUserNotification API to the UNNotification API on macOS. The new API requires that an application be code-signed in order for notifications to be displayed. If an application is not code-signed, notifications will emit a failed event on the Notification object.

Behavior Changed: Offscreen rendering will use 1.0 as default device scale factor.

Previously, OSR used the primary display's device scale factor for rendering, which made the output frame size vary across users. Developers had to manually calculate the correct size using screen.getPrimaryDisplay().scaleFactor. We now provide an optional property webPreferences.offscreen.deviceScaleFactor to specify a custom value when creating an OSR window. At first, if the property is not set, it defaults to the primary display's scale factor (preserving the old behavior). Starting from Electron 42, the default will change to a constant value of 1.0 for more consistent output sizes.

Behavior Changed: electron no longer downloads itself via postinstall script

Previously, the electron npm package would download the Electron binary from the repository's GitHub Releases in the package's postinstall script.

With recent supply chain security attacks against the npm ecosystem with postinstall scripts as a common attack vector, Electron will now download itself dynamically the first time that its main bin script is run (e.g. via npx electron). With this change, you can now use Electron with the npm --ignore-scripts flag. See RFC #22 for more context.

# won't install binary to `node_modules/electron`
npm install electron --save-dev --ignore-scripts

# will download the binary on demand before starting electron process
npx electron .

# subsequent runs will used the binary downloaded from the first run
npx electron .

If you need to download the Electron binary on-demand, you can now call the install-electron script, which contains the exact same code from the former postinstall script.

npm install electron --save-dev --ignore-scripts
npx install-electron --no

If you need to test changes across platforms or architectures, you should now use the ELECTRON_INSTALL_ARCH and ELECTRON_INSTALL_PLATFORM environment variables.

# before: pass npm config flag on install command
npm install --platform=mas electron --save-dev
# after: add env var when you first run the Electron command
npm install electron --save-dev
ELECTRON_INSTALL_PLATFORM=mas npx electron . --no

This also means the ELECTRON_SKIP_BINARY_DOWNLOAD environment variable is no longer supported, as its primary purpose was to prevent the postinstall script from running.

Removed: quotas object from Session.clearStorageData(options)

When calling Session.clearStorageData(options), the options.quotas object is no longer supported because it has been removed from upstream Chromium.

Deprecated: Passing only an array hslShift to nativeImage.createFromNamedImage()

Passing only an array hslShift to nativeImage.createFromNamedImage() is deprecated. You should now pass an options object with an hslShift property instead:

// Deprecated
nativeImage.createFromNamedImage(imageName, [0, 1, -1])
// Replace with
nativeImage.createFromNamedImage(imageName, {
  hslShift: [0, 1, -1]
})

Geplante Bruch-API-Änderungen (41.0)

Behavior Changed: PDFs no longer create a separate WebContents

Previously, PDF resources created a separate guest WebContents for rendering. Now, PDFs are rendered within the same WebContents instead. If you have code to detect PDF resources, use the frame tree instead of WebContents.

Under the hood, Chromium enabled a feature that changes PDFs to use out-of-process iframes (OOPIFs) instead of the MimeHandlerViewGuest extension.

Behavior Changed: Updated Cookie Change Cause in the Cookie 'changed' Event

We have updated the cookie change cause in the cookie 'changed' event. When a new cookie is set, the change cause is inserted. When a cookie is deleted, the change cause remains explicit. When the cookie being set is identical to an existing one (same name, domain, path, and value, with no actual changes), the change cause is inserted-no-change-overwrite. When the value of the cookie being set remains unchanged but some of its attributes are updated, such as the expiration attribute, the change cause will be inserted-no-value-change-overwrite.

Deprecated: showHiddenFiles in Dialogs on Linux

This property will still be honored on macOS and Windows, but support on Linux will be removed in a future version of Electron. GTK intends for this to be a user choice rather than an app choice and has removed the API to do this programmatically.

Geplante Bruch-API-Änderungen (40.0)

Deprecated: clipboard API access from renderer processes

Using the clipboard API directly in the renderer process is deprecated. If you want to call this API from a renderer process, place the API call in your preload script and expose it using the contextBridge API.

Behavior Changed: MacOS dSYM files now compressed with tar.xz

Debug symbols for MacOS (dSYM) now use xz compression in order to handle larger file sizes. dsym.zip files are now dsym.tar.xz files. End users using debug symbols may need to update their zip utilities.

Geplante Bruch-API-Änderungen (39.0)

Deprecated: --host-rules command line switch

Chromium is deprecating the --host-rules switch.

Du solltest stattdessen --host-resolver-rules verwenden.

Behavior Changed: window.open popups are always resizable

Per current WHATWG spec, the window.open API will now always create a resizable popup window.

To restore previous behavior:

webContents.setWindowOpenHandler((details) => {
  return {
    action: 'allow',
    overrideBrowserWindowOptions: {
      resizable: details.features.includes('resizable=yes')
    }
  }
})

Behavior Changed: NSAudioCaptureUsageDescription should be included in your app's Info.plist file to use desktopCapturer (🍏 macOS ≥14.2)

Per Chromium update which enables Apple's newer CoreAudio Tap API by default, you now must have NSAudioCaptureUsageDescription defined in your Info.plist to use desktopCapturer.

Electron's desktopCapturer will create a dead audio stream if the new permission is absent however no errors or warnings will occur. This is partially a side-effect of Chromium not falling back to the older Screen & System Audio Recording permissions system if the new system fails.

To restore previous behavior:

// main.js (right beneath your require/import statments)
app.commandLine.appendSwitch(
  'disable-features',
  'MacCatapLoopbackAudioForScreenShare'
)

Behavior Changed: shared texture OSR paint event data structure

When using shared texture offscreen rendering feature, the paint event now emits a more structured object. It moves the sharedTextureHandle, planes, modifier into a unified handle property. See the OffscreenSharedTexture API structure for more details.

Geplante Bruch-API-Änderungen (38.0)

Removed: ELECTRON_OZONE_PLATFORM_HINT environment variable

The default value of the --ozone-platform flag changed to auto.

Electron now defaults to running as a native Wayland app when launched in a Wayland session (when XDG_SESSION_TYPE=wayland). Users can force XWayland by passing --ozone-platform=x11.

Removed: ORIGINAL_XDG_CURRENT_DESKTOP environment variable

Previously, Electron changed the value of XDG_CURRENT_DESKTOP internally to Unity, and stored the original name of the desktop session in a separate variable. XDG_CURRENT_DESKTOP is no longer overridden and now reflects the actual desktop environment.

Entfernt: macOS 11 Unterstützung

macOS 11 (Big Sur) wird nicht mehr von Chromium unterstützt.

Ältere Versionen von Electron werden weiterhin auf Big Sur laufen, aber macOS 12 (Monterey) oder höher werden benötigt, um Electron v38.0.0 und höher laufen zu lassen.

Entfernt: plugin-crashed Ereignis

Das plugin-crashed Ereignis wurde von webContents entfernt.

Veraltet: webFrame.routingId Eigenschaft

Die routingId Eigenschaft wird von webFrame Objekten entfernt werden.

Du solltest stattdessen webFrame.frameToken verwenden.

Veraltet: webFrame.findFrameByRoutingId(routingId)

Die webFrame.findFrameByRoutingId(routingId) Funktion wird entfernt.

Du solltest stattdessen webFrame.findFrameByToken(frameToken) verwenden.

Geplante Bruch-API-Änderungen (37.0)

Utility Process unhandled rejection behavior change

Utility Processes will now warn with an error message when an unhandled rejection occurs instead of crashing the process.

To restore the previous behavior, you can use:

process.on('unhandledRejection', () => {
  process.exit(1)
})

Behavior Changed: process.exit() kills utility process synchronously

Calling process.exit() in a utility process will now kill the utility process synchronously. This brings the behavior of process.exit() in line with Node.js behavior.

Please refer to the Node.js docs and PR #45690 to understand the potential implications of that, e.g., when calling console.log() before process.exit().

Behavior Changed: WebUSB and WebSerial Blocklist Support

WebUSB and Web Serial now support the WebUSB Blocklist and Web Serial Blocklist used by Chromium and outlined in their respective specifications.

To disable these, users can pass disable-usb-blocklist and disable-serial-blocklist as command line flags.

Removed: null value for session property in ProtocolResponse

This deprecated feature has been removed.

Previously, setting the ProtocolResponse.session property to null would create a random independent session. This is no longer supported.

Using single-purpose sessions here is discouraged due to overhead costs; however, old code that needs to preserve this behavior can emulate it by creating a random session with session.fromPartition(some_random_string) and then using it in ProtocolResponse.session.

Behavior Changed: BrowserWindow.IsVisibleOnAllWorkspaces() on Linux

BrowserWindow.IsVisibleOnAllWorkspaces() will now return false on Linux if the window is not currently visible.

Geplante Bruch-API-Änderungen (36.0)

Behavior Changes: app.commandLine

app.commandLine will convert upper-cases switches and arguments to lowercase.

app.commandLine was only meant to handle chromium switches (which aren't case-sensitive) and switches passed via app.commandLine will not be passed down to any of the child processes.

If you were using app.commandLine to control the behavior of the main process, you should do this via process.argv.

Veraltet: NativeImage.getBitmap()

NativeImage.toBitmap() returns a newly-allocated copy of the bitmap. NativeImage.getBitmap() was originally an alternative function that returned the original instead of a copy. This changed when sandboxing was introduced, so both return a copy and are functionally equivalent.

Client code should call NativeImage.toBitmap() instead:

// Deprecated
bitmap = image.getBitmap()
// Use this instead
bitmap = image.toBitmap()

Removed: isDefault and status properties on PrinterInfo

These properties have been removed from the PrinterInfo Object because they have been removed from upstream Chromium.

Removed: quota type syncable in Session.clearStorageData(options)

When calling Session.clearStorageData(options), the options.quota type syncable is no longer supported because it has been removed from upstream Chromium.

Deprecated: null value for session property in ProtocolResponse

Previously, setting the ProtocolResponse.session property to null would create a random independent session. This is no longer supported.

Using single-purpose sessions here is discouraged due to overhead costs; however, old code that needs to preserve this behavior can emulate it by creating a random session with session.fromPartition(some_random_string) and then using it in ProtocolResponse.session.

Deprecated: quota property in Session.clearStorageData(options)

When calling Session.clearStorageData(options), the options.quota property is deprecated. Since the syncable type was removed, there is only one type left -- 'temporary' -- so specifying it is unnecessary.

Deprecated: Extension methods and events on session

session.loadExtension, session.removeExtension, session.getExtension, session.getAllExtensions, 'extension-loaded' event, 'extension-unloaded' event, and 'extension-ready' events have all moved to the new session.extensions class.

Entfernt: systemPreferences.isAeroGlassEnabled()

The systemPreferences.isAeroGlassEnabled() function has been removed without replacement. It has been always returning true since Electron 23, which only supports Windows 10+, where DWM composition can no longer be disabled.

https://learn.microsoft.com/en-us/windows/win32/dwm/composition-ovw#disabling-dwm-composition-windows7-and-earlier

Changed: GTK 4 is default when running GNOME

After an upstream change, GTK 4 is now the default when running GNOME.

In rare cases, this may cause some applications or configurations to error with the following message:

Gtk-ERROR **: 11:30:38.382: GTK 2/3 symbols detected. Using GTK 2/3 and GTK 4 in the same process is not supported

Affected users can work around this by specifying the gtk-version command-line flag:

$ electron --gtk-version=3   # or --gtk-version=2

The same can be done with the app.commandLine.appendSwitch function.

Geplante Bruch-API-Änderungen (35.0)

Behavior Changed: Dialog API's defaultPath option on Linux

On Linux, the required portal version for file dialogs has been reverted to 3 from 4. Using the defaultPath option of the Dialog API is not supported when using portal file chooser dialogs unless the portal backend is version 4 or higher. The --xdg-portal-required-version command-line switch can be used to force a required version for your application. See #44426 for more details.

Deprecated: getFromVersionID on session.serviceWorkers

The session.serviceWorkers.fromVersionID(versionId) API has been deprecated in favor of session.serviceWorkers.getInfoFromVersionID(versionId). This was changed to make it more clear which object is returned with the introduction of the session.serviceWorkers.getWorkerFromVersionID(versionId) API.

// Deprecated
session.serviceWorkers.fromVersionID(versionId)

// Replace with
session.serviceWorkers.getInfoFromVersionID(versionId)

Deprecated: setPreloads, getPreloads on Session

registerPreloadScript, unregisterPreloadScript, and getPreloadScripts are introduced as a replacement for the deprecated methods. These new APIs allow third-party libraries to register preload scripts without replacing existing scripts. Also, the new type option allows for additional preload targets beyond frame.

// Deprecated
session.setPreloads([path.join(__dirname, 'preload.js')])

// Replace with:
session.registerPreloadScript({
  type: 'frame',
  id: 'app-preload',
  filePath: path.join(__dirname, 'preload.js')
})

Deprecated: level, message, line, and sourceId arguments in console-message event on WebContents

The console-message event on WebContents has been updated to provide details on the Event argument.

// Deprecated
webContents.on('console-message', (event, level, message, line, sourceId) => {})

// Replace with:
webContents.on('console-message', ({ level, message, lineNumber, sourceId, frame }) => {})

Additionally, level is now a string with possible values of info, warning, error, and debug.

Behavior Changed: urls property of WebRequestFilter.

Previously, an empty urls array was interpreted as including all URLs. To explicitly include all URLs, developers should now use the <all_urls> pattern, which is a designated URL pattern that matches every possible URL. This change clarifies the intent and ensures more predictable behavior.

// Deprecated
const deprecatedFilter = {